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Notices 


Any reference to an IBM licensed program in this publication is not intended to state 
or imply that only IBM’s licensed program may be used. Any functionally equivalent 
product, program, or service that does not infringe any of IBM’s intellectual property 
rights can be used instead of the IBM product, program, or service. Evaluation and 
verification of operation in conjunction with other products, programs, or services, 
except those expressly designated by IBM, is the user’s responsibility. 

IBM might have patents or pending patent applications covering subject matter in this 
document. The furnishing of this document does not give you any license to these 
patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 
IBM Corporation 
500 Columbus Avenue 
Thornwood, NY 10594 
USA 

This publication may contain examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 


Programming Interface Information 

This book is intended to help you develop applications using the C++ class libraries 
provided with VisualAge C++. This publication documents General-Use 
Programming Interface and Associated Guidance Information provided by C++ 

General-Use programming interfaces allow the customer to write programs that obtain 
the services of VisualAge C++. 


Trademarks and Service Marks 


The following terms are trademarks of the International Business Machine 
Corporation in the United States or other countries or both: 


BookManager 
Common User Access 
CUA 
C Set ++ 

IBM 

IBMLink 


Open Class 
Operating System/2 
OS/2 

Presentation Manager 

VisualAge 

WorkFrame 
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UNIX is a registered trademark in the United States and other countries licensed 
exclusively through X/Open Company Limited. 

Other company, product, and service names, which may be denoted by a double 
asterisk (**), may be trademarks or service marks of others: 
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About This Book 

The IBM VisualAge C++: User Interface Class Library Reference (hereafter called 
Open Class Library Reference) provides a reference of all the classes for the User 
Interface Class Library, which is part of the VisualAge C++ product. 

The User Interface Class Library classes are divided between Volume II and Volume 
III of the Open Class Library Reference. Refer to “How This Book is Organized” for 
information on the content of the reference volumes. Within each volume, the classes 
are listed alphabetically for easy retrievability. Use this reference if you want to 
build applications with graphical user interfaces. 


Who Should Read this Book 

This book is intended for application programmers who want to develop portable C++ 
applications using the User Interface Class Library, part of the IBM Open Class 
Library product. You should be familiar with the IBM Operating System/2 (OS/2) 
2.0, 2.1, or 3.0 operating system and OS/2 Presentation Manager (PM). 

If you are not familiar with OS/2, refer to the programming guides in the OS/2 
Technical Library. 

For detailed information about C++ language keywords and definitions, refer to the 
VisualAge C++ Language Reference. 

Refer to the IBM VisualAge C++ Open Class Library User’s Guide for information on 
how to use the User Interface Class Library. 


Conventions Used in this Book 

New or unfamiliar terms appear in italics on their first occurrence in this reference. 
Acronyms and abbreviations are spelled out the first time they are used. The glossary 
also contains definitions for new terms, acronyms, and abbreviations. 

Static members are shown in bold within the cross reference tables. 

References to pages within this volume are indicated by the page number placed in 
parentheses. 


How This Book is Organized 

The User Interface Class Library classes are grouped into major categories. Volume 
II contains the classes grouped in the following categories: 


xvi 
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• Application Control Classes 

• Base Windows, Menus, Handlers, and Events 

• Basic Controls 

Volume III contains the classes grouped in the following categories: 

• Advanced Controls, Dialogs, and their Handlers 

• Direct Manipulation Classes 

• Two-Dimensional Graphic Classes 

• Dynamic Data Exchange Classes 

• Multimedia Classes 

Volume III also contains cross-reference information about the classes in Volume I, 
Volume II, and Volume III. 

Refer to “About the User Interface Class Library” on page xix for details on 
grouping categories. For information on class descriptions by name, see Part 1, 
“Description of Classes.” 

In this book, classes, member functions, and enumerations might have the following 
sections: 


Portability Considerations 
| Motif Motif Information 

IPM Presentation Manager Information 

These sections contain information that is specific to a particular platform or 
suggestions for developing portable applications. Each section is designated by the 
icon shown so that information for a particular platform is easy to find. 

Note that some members have a Platform Support Table in the online reference. If a 
member function is overloaded, one overload might have one condition, while a 
second overload has a different condition. For example, in 
IBaseSpinButton::initialize, one implementation is for both AIX and OS/2, while 
another implementation is for OS/2 only. Also, some functions with only one 
implementation might be supported on only one platform. This is indicated in the 
Platform Support Table as well. This table lists each platform in the heading and the 
table entries explain if the function is supported, not supported, or silently ignored. 

In the hardcopy reference, this information is provided to the right of the member’s 
declaration. For example: 
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[] virtual void Supported On: 

initial ize(); PM 


| void Supported On: 

initial ize( unsigned long windowld, PM, Motif 

const IWindowHandl e& parent, 
const IWindowHandl e& owner, 
unsigned long style, 
const IRectangle& initial); 

Volume III also contains a number of cross-references likely to be of use to you in 
your development activity. 

Appendix A, “Summary of Changes” lists the changes to classes and member 
functions in this release. 

Appendix B, “New Color Support” provides a listing of the new set of functions used 
by the User Interface Class Library for color manipulation. 

Appendix C, “Using Extended Style Support” provides solutions to a number of 
window style issues when using the User Interface Class Library. 

Appendix D, “Obsolete and Ignored Members Cross-Reference” contains two 
cross-reference tables. The first table lists obsolete classes and members in the User 
Interface Class Library. The second table lists classes and members that the User 
Interface Class Library does not support and subsequently ignores. 

Appendix E, “Handlers for Controls Cross-Reference” contains a list of handlers and 
the controls to which you can attach them. 

Appendix F, “Classes and Their Styles Cross-Reference” contains a list of styles, 
showing the styles each class has, and whether the User Interface Class Library for 
AIX supports the style. 

Appendix G, “Classes and Header Files Cross-Reference” contains two 
cross-reference tables. You can use the first to find the name of the header file that 
contains a particular class. The second helps you find what classes are in a single 
header file. 

In “Bibliography” you can find books related to the C Set ++ for AIX User Interface 
Class Library and the VisualAge C++ User Interface Class Library, C and C++ books, 
as well as other useful publications. 
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About the User Interface Class Library 

The User Interface Class Library is one of the class libraries included in the IBM 
VisualAge C++ for OS/2 product. It is a C++ class library that simplifies how you 
develop OS/2 applications with graphical user interfaces (GUI). The User Interface 
Class Library provides classes that you can use in your applications and reuse to 
extend your applications. 

You can use the User Interface Class Library classes to build applications that 
simulate Common User Access (CUA) workplace look and feel and take advantage of 
PM features. You can also use the User Interface Class Library to develop 
applications that are portable between the AIX and OS/2 operating systems. 

The User Interface Class Library contains over 400 classes and over 4000 member 
functions. To assist you in learning about the classes and to guide you as you start 
developing applications, we organized the classes into the following basic categories: 

• Application Control Classes 

• Data Types and Base Classes 

• Base Windows, Menus, Handlers, and Events 

• Basic Controls 

• Advanced Controls, Dialogs, and their Handlers 

• Direct Manipulation Classes 

• Dynamic Data Exchange Classes 

• Two-Dimensional Graphic Classes 

• Multimedia Classes 

Application Control Classes: Provide support for the application, threads, timers, 
profiles, and the resources used by the applications you develop. 

Data Types and Base Classes: Provide support for the exceptions, trace output, 
messages, strings, notifications, and window geometry used by the applications you 
develop. 

Model basic data types, such as strings, points, and rectangles. These classes hide the 
structure of the data, while providing the capability to access and alter the data. In 
addition, a set of handle classes are provided to access window or application-specific 
handles. 

Base Windows, Menus, Handlers, and Events: Provide support for the basic 
windows, handlers, events, and menus used by the applications you develop. 

Encapsulates the basic graphical building blocks that are used to construct application 
windows. This allows window position and appearance (parent windows) to be 
separated from event handling (owner windows). 
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Encapsulate the user’s interaction with application windows. The library creates 
event objects as a result of some action by the user or by other applications. These 
event objects contain information about what occurred; they are passed to handler 
objects for processing. Each window has some default event processing; however, 
the application can create instances of the handler classes to process certain event 
objects to override the default behavior. 

Use handlers to override or augment a control’s default behavior. For example, use a 
handler when you want to take some action based on user input such as selecting a 
button or list box item. 

Basic Controls: Provide support for the basic controls like entry field, static text and 
buttons used by the applications you develop. 

Advanced Controls, Dialogs, and their Handlers: Provide support for the advanced 
controls like container, notebook, tool bar, and the font and file dialogs used by the 
applications you develop. 

Direct Manipulation Classes: Provide support for the direct manipulation used by 
the applications you develop. 

Dynamic Data Exchange Classes: Provide support for the Dynamic Data Exchange 
(DDE) used by the applications you develop. 

Two-Dimensional Graphic Classes: Provide support for the 2D graphic elements 
used by the applications you develop. 

Multimedia Classes: Provide support for the multimedia devices and controls used 
by the applications you develop. 

See “Conventions Used in this Book” on page xvi for tips on using this document. 


User Interface Class Library Conventions 

This section describes the User Interface Class Library conventions for the following: 

• File names 

• Class names and member names 

• Function return types 

• Function arguments 

• Examples 
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File Names 


File names have a maximum of eight characters. All files provided by the User 
Interface Class Library begin with the letter “I” for IBM, for example, IAPP.HPP. 
The following table lists file names, file extensions, and a brief description. 


File Name and 

Extension 

Description 

Jxxxxxxx.CPP 

Source code 

Ixxxxxxx.H 

Constant definitions file 

Ixxxxxxx.HPP 

Class interface file 

Ixaxrxx.INL 

Inline functions 


Refer to the Open Class Library Reference Volume III for cross-reference tables for 
the header files and the classes they contain. 


The Open Class Library product files begin with the letters “CPP”. The following 
table lists some file names, files extensions, and a brief description. 


File Name and 
Extension 

Description 

CPPOOC3I.LIB 

Import library file 

CPPOOB3.DLL 

Multithreaded dynamic-link library file containing the base library 
classes (Collection/Application Support classes) 

CPPOOB3.DEF 

Import module-definition file used to rebuild the CPP00B3.DLL file 

CPPOOD3.DLL 

Multithreaded dynamic-link library file containing the dynamic data 
exchange classes. 

CPPOOD3.DEF 

Import module-definition file used to rebuild the CPP00D3.DLL file 

CPPOOM3.DLL 

Multithreaded dynamic-link library file containing the Multimedia 
classes. 

CPPOOM3.DEF 

Import module-definition file used to rebuild the CPP00M3.DLL file 

CPPOOU3.DLL 

Multithreaded dynamic-link library file containing the User Interface 
Base library classes. 

CPPOOU3.DEF 

Import module-definition file used to rebuild the CPP00U3.DLL file 

CPPOOC3.LIB 

Static object library 

CPP.NDX 

Index for online help (Does not contain class::member syntax for 
members) 

CPPBRS.NDX 

Index for online help (Contains class::member references) 
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File Name and 
Extension 

Description 

CPPLINF 

Online help and online documentation files 

CPPOOC3U.MSG 

Exception messages 


Class Names and Member Names 

The following rules were used for naming the User Interface Class Library classes 
and members: 

• Type names begin with a capital letter. 

• Global type names begin with the letter “I”, as in ICurrentApplication. 

• Member names, including member functions, member data, and enumerations, 
begin with lowercase letters, as in autoSize data member. 

Note: In this book, single-word member functions have ClassName:: added to 
them; for example, the member function “show” appears as 
IWindow::show. 

Function Return Types and Function Arguments 

To follow the User Interface Class Library conventions, pass objects as const 
references or references and return objects by value rather than by reference. Pass 
objects by pointer rather than by reference when you want a parameter to use its 
default. 

Function return types for the various functions are as follows: 

• A Boolean (true or false). Use IBase::Boolean because it is portable between 
OS/2 and AIX. The following is an example of a testing function: 

IBase::Boolean isValid() const; 

Note: The User Interface Class Library returns a 0 if false and a nonzero if true, 
so do not test for the following: 

if (isVal id() = = true) 

Instead use: 
if (isValid()) 

• An object. Accessor functions typically return an object. An accessor returns 
information about the elements of a data type. The following example returns a 
pointer to an IWindow object. 

IWindow* owner(); //Returns a pointer to an object 

• An object reference. Functions that act on an object return a reference to the 
object on which they were called. For example: 
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IWindow& hide(); 

This lets you chain function calls together, as shown in the following example: 
window.moveTo(IPoint(lQ,10)),show(); 

Function arguments are passed in the following ways: 

• Built-in types (integers or doubles, for example) and enumerations are passed in 
by value. 

• Objects are passed by reference. If the argument is not modified by the function, 
it is passed as a const reference. 

• Optional objects are passed by pointer. This allows a 0 pointer to signify that no 
object is being passed. 

• IWindow objects are passed by pointer. 

• IContainerObjects are passed by pointer. 

• Strings are passed as a const char *. This enables you to pass either an IString 
object or an array of characters. 

A Note about Samples and Examples 

This Open Class Library Reference contains examples and references to samples. 
Samples, including the Hello World sample application, are shipped with the User 
Interface Class Library product in the following directory: 

\ibmcpp\samples\ioc 

Examples, on the other hand, exist only in the Open Class Library Reference. 

The samples and examples in the User Interface Class Library books explain elements 
of the User Interface Class Library. They are coded in a simple style. They do not 
try to conserve storage, check for errors, achieve fast run times, or demonstrate all 
possible uses of a particular class or function. The samples and examples are 
instructive, but not necessarily intended for productive use. 
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Advanced Control, Dialog, and Handler Classes 

Provide support for the advanced controls, such as container, notebook, and toolbar, 
and for the font and file dialogs used by the applications you develop. 

ISequence 
•—ICnrObjectSet 
ISet 

•—ICnrControlList 
IBase 
—I Bit Flag 

—IContainerControl::Attri bute 
|—INotebook::PageSettings::Attribute 
|—IAnimatedButton::Style 
—IBitmapControl::Style 
—ICanvas::Style 
—ICircularSlider::Style 
—IContainerControl::Style 
—ICustomButton::Style 
|—IDrawingCanvas::Style 
—IFileDialog::Style 
—IFontDialog::Style 
—IGraphicPushButton::Style 
|—IlconControl::Style 
—IMultiCelICanvas::Style 
—INotebook::Style 
—ISetCanvas::Style 
—ISpl itCanvas::Style 
—IToolBar::Style 
—ITool BarButton::Style 
—IToolBarContainer::Style 
*—IViewPort::Style 
—ICnrAllocator 
—IFi1eDialog::Settings 
—IFontDialog::Settings 
—IHandle 

*—IPageHandle 
L IVBase 

—IContainerControl::Col umnCursor 
—IContainerControl::CompareFn 
—INotebook::Cursor 
—IContainerControl::Fi 1 terFn 
—IToolBar::FrameCursor 
—IContainerColumn 
'—IContai nerObject 


2 Open Class Library Reference 




Advanced Control, Dialog, and Handler Classes .. 

IBase 
L IVBase 
—I Event 

|—ICnrDrawBackgroundEvent 
\— IControlEvent 
|— ICnrEvent 

—ICnrEditEvent 

—ICnrBeginEditEvent 
—ICnrEndEditEvent 
*— ICnrReal1ocStringEvent 
—ICnrEmphasisEvent 
—ICnrEnterEvent 
—ICnrHelpEvent 
—ICnrQueryDeltaEvent 
*— ICnrScrol1 Event 
—ICustomButtonDrawEvent 
|—IDrawItemEvent 

|—ICnrDrawItemEvent 
INotebookDrawItemEvent 
*—IPageEvent 

—IPageHelpEvent 
—IPageRemoveEvent 
—IPageSelectEvent 
*—IFileDialogEvent 
—IHandler 

—ICnrDrawHandler 
—ICnrEditHandler 
—ICnrHandler 

—ICustomButtonDrawHandl er 
—IFi leDialogHandler 
—I FIyOverHelpHandl er 
—IFontDialogHandler 
—IMenuHandler 

L ICnrMenuHandler 
—IPageHandler 
—IShowListHandler 
—ISpinHandler 
—IWindowNotifyHandler 
|—INotebookNotifyHandler 
*—ITextControlNotifyHandler 

1 —ICi rcularSliderNotifyHandler 
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Advanced Control, Dialog, and Handler Classes ... 

IBase 
L IVBase 

—INotifier 
*—IWindow 
—IControl 

—IBaseListBox 

1 —ICol1ectionViewListBox 
—ICanvas 

|—IDrawingCanvas 
—IMultiCelICanvas 
|— ISetCanvas 
|—IToolBar 
L- IToolBarContainer 
—ISplitCanvas 
*—IViewPort 
—IContainerControl 
|—INotebook 
ITextControl 
—IButton 

|— ICustomButton 
|—IAnimatedButton 
*—IToolBarButton 
*—IPushButton 

1 —IGraphicPushButton 
—ICircularSlider 
—I EntryFi el d 
L IBaseComboBox 

1 —ICol1ectionViewComboBox 

|—I FI yText 
*—IStaticText 

|—IBitmapControl 
*—IlconControl 
L- IlnfoArea 
*— IFrameWindow 
|—IFi 1 eDialog 
|—IFontDialog 
—IToolBarFrameWindow 
—I RefCounted 

•—IStringGeneratorFn 

|—IStringGeneratorMemberFn 
1 —IStri ngGeneratorRefMemberFn 
—IContai nerControl::Iterator 
—IContainerControl::ObjectCursor 
—INotebook::PageSettings 
—IContainerControl::TextCursor 
*—IToolBar::WindowCursor 
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Direct Manipulation Classes 

Provide support for the direct manipulation used by the applications you develop. 

I DM 

IBase 
—IBitFlag 

*—IDMImage::Style 
*—IVBase 

—IDMImage 
—IDMItemProvider 

*—IDMItemProviderFor 
—IDMRenderer 

|—IDMSourceRenderer 
IDMTargetRenderer 
—IEvent 
L IDMEvent 

|—IDMSourceBeginEvent 
—IDMSourceDiscardEvent 
—IDMSourceEndEvent 
—IDMSourcePrintEvent 
—IDMSourceRenderEvent 
*—IDMSourcePrepareEvent 
—IDMTargetEndEvent 
—IDMTargetEvent 

|—IDMTargetDropEvent 
|—IDMTargetEnterEvent 
*—IDMTargetLeaveEvent 
*— IDMTargetHelpEvent 
—IHandler 
1 —IDMHandler 

|—IDMSourceHandler 
*— IDMTargetHandler 
—IRefCounted 
—IDMItem 

—IDMCnrltem 
|—IDMEFItem 
—IDMMenuItem 
|—IDMMLEItem 
—IDMTBarButtonltem 
*— IDMToolBarltem 
*—IDMOperation 

|—IDMSourceOperation 
*— IDMTargetOperation 
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2D Graphic Classes 

Provide support for the 2D graphic elements used by the applications you develop. 

IBase 

—IGraphicBundle 
—IHandle 

*—IRegionHandle 
—ITransformMatrix 
L-IVBase 

—IGList::Cursor 
—IFont::FaceNameCursor 
—I Font 
—IGraphic 

—IG3PointArc 
blGArc 
—IGBitmap 
—IGE11 ipse 
—IGLi ne 
blGList 
blGPie 
•—IGChord 
—IGPolyline 
*—IGPolygon 
—IGRectangle 
blGRegion 
—I GString 
—IGraphicContext 
—I Font::PointSizeCursor 


Dynamic Data Exchange Classes 

Provide support for the Dynamic Data Exchange (DDE) used by the applications you 
develop. 

ISet 

\— IDDEActiveServerSet 
1 —IDDECt i entHotLinkSet 
IBase 
—IDDE 

—IDDEActiveServer 
L IVBase 
—I Event 

—IDDEBeginEvent 
—IDDEEndEvent 

1 —IDDEC1ientEndEvent 
*—IDDEEvent 

blDDEAcknowledgeEvent 

blDDEAcknowledgeExecuteEvent 
—IDDEAcknowledgePokeEvent 
—IDDEC1 i entAcknowledgeEvent 
•—IDDEServerAcknowledgeEvent 
*—IDDESetAcknowledgelnfoEvent 
—IDDEC1ientHotLinkEvent 
—IDDEDataEvent 
—IDDEExecuteEvent 
—IDDEPokeEvent 
—IDDERequestDataEvent 
*—IDDEServerHotLinkEvent 
—IHandler 

|—IDDEC1 ientConversation 
IDDETopicServer 
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Multimedia Classes 

Provide support for the multimedia devices and controls used by the applications you 
develop. 

IBase 

|—IMMAudioBuffer 
L IVBase 

—IMMAudioCDContents::Cursor 
—IErrorlnfo 

IMMErrorlnfo 
—IEvent 

—IMMCuePointEvent 
|—IMMDeviceEvent 
—IMMNotifyEvent 
|—IMMPassDeviceEvent 
—IMMPositionChangeEvent 
—IHandler 

|—ICommandHandler 

1 —IMMP1ayerPanel Handler 
—IMMDeviceHandler 

IMMRemovabl eMediaHandl er 
—IMMAudioCDContents 
—IMMSpeed 
—IMMTime 

|—IMMHourMinSecFrameTime 
|—IMM24FramesPerSecondTime 
—IMM25FramesPerSecondTime 
IMM30FramesPerSecondTime 
|—IMMHourMinSecTime 
—IMMMi 11 i secondTime 
—IMMMinSecFrameTime 
L IMMT rackMinSecFrameTime 
—INotifier 

—IStandardNotifier 
|—IMMDevice 
|—IMMAmpMixer 
1 —IMMP1ayableDevice 
—IMMFi1eMedia 
|—IMMRecordable 

1 —IMMConfigurableAudio 
|—IMMDigitalVideo 
*—IMMWaveAudio 
*—IMMSequencer 
*— IMMRemovableMedia 
|—IMMAudioCD 
l IMMCDXA 
IMMMasterAudio 
*—IWindow 
*—IControl 
*—ICanvas 

1 —IMultiCell Canvas 
1 —IMMP1ayerPanel 
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IAnimatedButton 



lAnimatedButton 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

ICustomButton 

IAnimatedButton 


_.None. 

_-ianimbut.hpp 


Member 

Page 

Constructor 

12 

animate WhenLatched 

15 

animationRate 

9 

bitmap 

10 

bitmapCount 

11 

calcMinimumSize 

14 

classDefaultStyle 

15 

con vertT oGUISty le 

12 

currentB itmaplndex 

11 

defaultStyle 

13 

disable Animate WhenLatched 

9 


Member Page 

enableAnimateWhenLatched 9 

isAnimatedWhenLatched 9 

isAnimationStarted 9 

latch 10 

setAnimationRate 10 

setBitmaps 11 

setCurrentBitmapIndex 11 

setDefaultStyle 13 

start Animation 10 

stop Animation 10 

~I AnimatedB utton 12 


The IAnimatedButton class creates and manages the animated button control window. 
A set of bitmaps are specified for the button to use for animation. During animation, 
the button cycles through the bitmaps on a time interval. 

The bitmap set can be specified by the application by providing the resource ID of 
the first bitmap and the number of bitmaps to be used. The bitmap set can also be 
specified by using one of the animated bitmap sets that are provided by the library for 
standard multimedia actions. 

If the button text is not visible, the current animated bitmap is centered in the button, 
but it is not resized. If the button text is visible, the current animated bitmap is 
centered horizontally and positioned vertically along the top of the button with the 
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text centered horizontally immediately below the bitmap. No clipping is done for the 
bitmap, so it can paint outside the button border if the button is too small. 


Public Functions 
Animation 

Use these members to control the animation of the button. 


animationRate 

Returns the current animation rate for the button. The animation rate is specified in 
thousandths of a second. 

unsigned long Supported On: 

animationRate() const; PM 

disableAnimateWhen Latched 

Removes the animateWhenLatched style for the button. 

virtual IAnimatedButton& 
disableAnimateWhenLatched(); 

enableAnimateWhenLatched 

Sets the animateWhenLatched style for the button. 

virtual IAnimatedButtonS Supported On: 

enableAnimateWhenLatched( Boolean enable = true); PM 

isAnimatedWhen Latched 

Returns true if the animateWhenLatched style is set. 

Boolean 

isAnimatedWhenLatched() const; 

isAnimationStarted 

Returns true if the button is currently animated. 

Boolean Supported On: 

isAnimationStarted() const; PM 


Supported On: 

PM 


Supported On: 

PM 
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Puts the button in a latched or unlatched state based on the latched parameter. The 
value of the refresh parameter will determine if the button is painted. 


virtual IAnimatedButton& 
latch( Boolean latched = true. 
Boolean refresh = true); 


Supported On: 

PM 


setAnimationRate 

Sets the animation rate for the button in thousandths of a second. The default 
animation rate is one second. 

The animation rate represents the amount of time that each bitmap is displayed when 
the button is animated. 

Note: This class uses the ITimer (Vol. II) class to control animation. Refer to the 
ITimer (Vol. II) class for more information. 


virtual IAnimatedButton& 
setAnimationRate( unsigned long newRate = 1000); 


Supported On: 

PM 


startAnimation 

Starts the animation of the button. If you specify an index, the bitmap at the index is 
the first bitmap displayed. 


virtual IAnimatedButton& 
startAnimation( unsigned long index = 0); 


Supported On: 

PM 


Exceptions 

IlnvalidParameter The specified bitmap index is invalid. 


stopAnimation 

Stops the animation of the button. 


virtual IAnimatedButton& 
stopAnimation(); 


Supported On: 

PM 


Bitmaps 

Use these members to set and query the bitmaps that are displayed for a button. 
-Returns the handle of the specified bitmap. 
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virtual IBitmapHandle Supported On: 

bitmap( unsigned long index = 0) const; PM 

_Returns the number of bitmaps specified for the button. 


virtual unsigned long Supported On: 

bitmapCount() const; PM 

currentBitmapIndex 

Returns the index of the bitmap that is currently displayed for the button. 


virtual unsigned long Supported On: 

currentBitmapIndex() const; PM 

_Sets the bitmaps to be used for the button. If this function is called more than once, 
the button uses only the bitmaps specified in the last call. 


Q virtual IAnimatedButton& Supported On: 

setBitmaps( AnimatedBitmaps bitmaps); PM 

This function loads the specified resource bitmap set that the library provides. 


Exceptions 

IlnvalidParameter The animated bitmap set identifier is invalid. 


g virtual IAnimatedButton& 

setBitmaps( const IResourceId& firstBitmap, 
unsigned long count); 

The bitmaps must be sequential, starting with the value specified as the first bitmap 
ID and continuing for the specified bitmap count. 

setCurrentBitmapIndex 

Sets the index of the bitmap that is currently displayed for the button. 


Supported On: 

PM 


virtual IAnimatedButton& 

setCurrentBitmaplndex( unsigned long index = 0); 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign 
IAnimatedButton objects because both the copy constructor and assignment operator are private 
functions. 
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lAnimatedButton 

[J IAnimatedButton( unsigned long id. Supported On: 

IWindow* parent, PM 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Creates an IAnimatedButton with the specified window ID, parent and owner 
windows, screen position and size, and window style. 

Exceptions 

IlnvalidParameter The parent window pointer is invalid. 


2 IAnimatedButton( const IWindowHandle& handle); Supported On: 

PM 


Creates an IAnimatedButton object for the specified button control that has a 
user-button style. 

IAnimatedButton 


virtual 

'IAnimatedButtonO; 


Supported On: 

PM 


Styles 

Use these style members to set and query IAnimatedButton styles. You can use these styles with 
the styles defined by the following nested classes: 

IWindow::Styles (Vol. II) 

IControl::Styles (Vol. II) 

IButton::Styles (Vol. II) 

ICustomButton:: Styles (p. 260) 


convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 


virtual unsigned long 
convertToGUIStyle( const IBitFlag& style, 

Boolean extendedOnly = false) const; 


Supported On: 

PM 
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—Returns the default style. The default style is classDefaultStyle unless you have 
changed the style using setDefaultStyle. 

static Style Supported On: 

defaultStyle(); PM 


setDefaultStyle 

Sets the default style for all subsequent animated buttons. 

style Use the styles provided by IAnimatedButton::Style to specify the default 

style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM 


Inherited Public Functions 


ICustomButton 

backgroundColor 

isAutoLatchEnabled 

resetLatchedB ackgroundColor 

convertToGUIStyle 

isLatched 

resetLatchedForegroundColor 

defaultStyle 

i sLatchedB ackgroundColorHalftone 

setDefaultStyle 

disableAutoLatch 

isLatchingEnabled 

setLatchedB ackgroundColor 

disableLatching 

latch 

setLatchedForegroundColor 

enableAutoLatch 

latchedB ackgroundColor 

setUserData 

enableLatching 

latchedForegroundColor 

unlatch 


IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableNotification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 
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IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Layout Support 

These members manage the layout of an animated button. 

calcMinimumSize 

Returns the recommended minimum size of this animated button control. The size is 
based on the bitmap, button text, and the current font. 

virtual ISize Supported On: 

calcMinimumSize() const; PM 


Inherited Protected Functions 


ICustomButton 

calcMinimumSize 




INotifier 

addObserver 

notifyObservers 

observerList 
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Note: Members of IWindow (Vol. II) are not shown. 

Public Data 
Styles 

Use these style members to set and query IAnimatedButton styles. You can use these styles with 
the styles defined by the following nested classes: 

IWindow::Styles (Vol. II) 

IControl::Styles (Vol. II) 

IButton::Styles (Vol. II) 

ICustomButton::Styles (p. 260) 

animateWhenLatched 

Starts animation automatically when the button is in the latched state and stops 
animation when the button is in the unlatched (default) state. 

static const Style 
animateWhenLatched; 

classDefaultStyle 

Specifies the original default style for this class, which is IWindow::visible. 

static const Style Supported On: 

classDefaultStyle; PM 


Inherited Public Data 



Supported On: 

PM 
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IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveCoiorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IAnimatedButton contains the following nested classes: 
IAnimatedButton::Style (see page 17) 


Animated Bitmaps 

AnimatedBitmaps { 

rewind, stop, pause, play, fastForward, 

record, mute, trackAdvance, trackReverse, stepForward, 

stepBackward, scanForward, scanBackward, eject, volumellp, 

volumeDown 

}; 


Enumeration that defines identifiers for each of the provided animated bitmap 
resource sets. IBM User Interface Class Library provides these bitmaps for standard 
multimedia operations. 
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IAnimatedButton::Style 


IBase 

IBitFlag 

IAnimatedButton:: Style 


_.None. 

_Janimhut.hpp 

The IAnimatedButton::Style class provides a set of valid styles for the static member 
functions of the class IAnimatedButton. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBitmapControl 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IStaticText 

IBitmapControl 


IlconControl 


—ibmpctl.hpp 


Member 

Page 

Member 

Page 

Constructor 

19 

moveS izeTo 

22 

bitmap 

18 

setBitmap 

19 

calcMinimumSize 

23 

setDefaultStyle 

21 

classDefaultStyle 

24 

sizeToBitmap 

24 

convertToGUIStyle 

21 

'IBitmapControl 

21 

defaultStyle 

21 




Objects of the IBitmapControl class create and manage bitmap controls. A bitmap 
control draws a bitmap for its background. 

IMotifl AIX does not support the ISystemBitmapHandle class. Therefore, you cannot use 
the constructor that takes an ISystemBitmapHandle object as a parameter. 


Public Functions 
Bitmaps 

Use these members to query and set the bitmap for the bitmap control. You can query the 
handle of the current bitmap. You can change the bitmap of the bitmap control using these 
functions. 

-Returns the handle to the bitmap. 
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IBitmapHandle Supported On: 

bitmap() const; PM, Motif 

.Changes the bitmap used by the IBitmapControl object. 


Q virtual IBitmapControl& Supported On: 

setBitmap( unsigned long bitmapld); PM, Motif 

Set the bitmap using the default resource library with the specified bitmap id. 

§ virtual IBi tmapControl & Supported On: 

setBitmap( const IResourceId& bitmapld); PM, Motif 

Set the bitmap by specifying an IResourceld. If you want to load the bitmap from a 
specific resource library, use this function. 

g virtual IBi tmapControl & Supported On: 

setBitmap( const IBitmapHandle& handle); PM, Motif 

Set the bitmap using an existing bitmap handle. 

0 virtual IBi tmapControl & Supported On: 

setBitmap( ISystemBitmapHandle: identifier bitmap); PM 

Set the bitmap using a system bitmap. 

Constructors 

You can construct and destruct objects of the IBitmapControl class. You cannot copy or assign 
IBitmapControl objects because both the copy constructor and the assignment operator are private 
functions. 


IBitmapControl 

Q IBitmapControl ( unsigned long id. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IResourceId& bitmapld, 

const IRectangle& initial = IRectangle ( ), 

const Style& style = defaultStyle ( )); 

Create a bitmap control using the specified window ID, parent and owner windows, 
resource library with its specified bitmap ID, screen position and size, and window 
style. If you have not already loaded it from the .DLL or .EXE of your choice, use 
this constructor. 
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Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


2 IBitmapControl ( unsigned long id. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

unsigned long bitmapld, 

const IRectangle& initial = IRectangle ( ), 

const Style& style = defaultStyle ( )); 

Create a bitmap control with the specified ID, parent and owner windows, default 
resource library with its specified bitmap ID, and window style. If you have not 
already loaded the bitmap and you want load it from the default resource library, use 
this constructor. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


0 IBitmapControl ( unsigned long id. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IBitmapHandle& bitmapld = IBitmapHandle ( ), 
const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Create a bitmap control with the specified window ID, parent and owner windows, 
bitmap, screen position and size, and window style. If you already have a bitmap 
handle, use this constructor. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


J] IBitmapControl ( unsigned long id. Supported On: 

IWindow* parent, PM 

IWindow* owner, 

ISystemBitmapHandle::Identifier bitmapld, 
const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Create a bitmap control with the specified window ID, parent and owner windows, 
specified system bitmap, screen position and size, and window style. If you want to 
use a system bitmap, use this constructor. 
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Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


g IBitmapControl ( unsigned long id. Supported On: 

IWindow* parentDialog); PM, Motif 

Create an IBitmapControl object for the specified bitmap dialog control. 

g IBitmapControl ( const IWindowHandl e& handle); Supported On: 

PM, Motif 

Create an IBitmapControl object for the specified bitmap control's window handle. 

IBitmapControl 

virtual Supported On: 

'IBitmapControl (); PM, Motif 


Styles 

These style members provide valid styles for IBitmapControl ::setDefaultStyle and for the 
constructor of the IBitmapControl (p. 18) class. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 


virtual unsigned long 
convertToGUIStyle( const IBitFlag& style, 

Boolean extendedOnly = false) const; 


Supported On: 

PM 


—Returns the default style. This style is classDefaultStyle (p. 24) unless you have 
changed it using setDefaultStyle (p. 21). 


static Style Supported On: 

defaul tStyl e(); PM. Motif 


setDefaultStyle 

Sets the default style for all subsequent bitmap controls. 
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static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Window Positioning 

Use these members to set the size and position of windows. 
_ Changes the position and size of the window. 


virtual IBitmapControl& Supported On: 

moveSizeTo( const IRectangle& rectangle); Motif 

j ~ This IWindow function is overridden to handle bitmap sizing and positioning in 

Motif. 


Inherited Public Functions 


IStatieText 

alignment 

enableFillBackground 

isStrikeout 

backgroundColor 

enableHalftone 

isUnderscore 

convertToGUIStyle 

enableStrikeout 

limit 

defaultStyle 

enableUnderscore 

moveSizeTo 

disableFillBackground 

fiUColor 

resetFillColor 

disableHalftone 

foregroundColor 

setAlignment 

disableStrikeout 

hasFillBackground 

setDefaultStyle 

disableUnderscore 

isHalftone 

setFillColor 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableN otification 

isEnabledForNotification 
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IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Layout Support 

Layout is information used by the canvas classes to provide dialog-like behavior. 

calcMinimumSize 

Returns the minimum size this bitmap control can be based on the actual size of the 
currently set bitmap. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The call to determine the size of the bitmap failed. The bitmap may be 

corrupted. 


Inherited Protected Functions 


IStaticText 

calcLimitSize 

calcMinimumSize 

passEventToOwner 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 
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Public Data 
Styles 

These style members provide valid styles for IBitmapControl::setDefaultStyle and for the 
constructor of the IBitmapControl (p. 18) class. 

classDefaultStyle 

Returns the original default style for this class, which is IWindow::visible. 

static const Style Supported On: 

classDefaultStyle; PM. Motif 


sizeToBitmap 

Sizes the window to the size of the currently set bitmap. 


static const Style 
sizeToBitmap; 


Supported On: 

PM. Motif 


Inherited Public Data 


IStatieText 

bottom 

halftone 

strikeout 

center 

halftoneld 

strikeoutld 

classDefaultStyle 

left 

top 

flllBackground 

limitld 

underscore 

fillBackgroundld 

mnemonic 

underscoreld 

fillColorld 

right 

vertCenter 


ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 
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IWindow 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IBitmapControl contains the following nested classes: 
IBitmapControl::Style (see page 26) 
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IBitmapControl::Style 


IBase 

IBitFlag 

IBitmapControl:: Style 


_.None. 

—ibmpctl.hpp 

The nested class IBitmapControl::Style provides a set of valid styles for the 
IBitmapControl (p. 18) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICanvas 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ICanvas 


IDrawingCanvas 


ISplitCanvas 


IMultiCellCanvas 


I ViewPort 


ISetCanvas 




—icanvas.hpp 




Member 

Page 

Member 

Page 

Constructor 

28 

layoutSize 

34 

areChildrenReversed 

33 

matchForMnemonic 

30 

backgroundColor 

28 

origDefaultButtonHandle 

30 

calcMinimumSize 

33 

passEventT oO wner 

32 

classDefaultStyle 

35 

registerCallbacks 

32 

con vertT oGUIS ty le 

31 

setDefaultStyle 

31 

defaultPushButton 

29 

setLayoutDistorted 

30 

defaultStyle 

31 

setLayoutSize 

34 

fixupChildren 

34 

unregisterCallbacks 

33 

isTabStop 

29 

“ICanvas 

29 

layout 

34 




Objects of the ICanvas class provide dialog-like behavior for its child windows. This 
support includes: 

• Transferring the input focus to a child window that can accept it 

• Handling tab and cursor movement keys by moving the input focus between child 
windows 

• Allowing the client window or the frame window to be the central point for 
processing command events 

• Allowing the frame window to change the appearance of the mouse pointer 
Additionally, this class provides the above behavior for all derived classes. 
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As a result, you can use any of the canvas classes as the client window for a frame 
window that needs several controls that can accept the input focus. To specify the 
client window for an IFrameWindow, use IFrameWindow::setClient (Vol. II). 

Unlike other canvas classes, ICanvas does not alter the size or position of its child 
windows. Others, like IMultiCellCanvas (p. 1049), ISetCanvas (p. 1138), 
ISplitCanvas (p. 1157), and IViewPort (p. 1239), provide special layout rules for 
sizing and positioning their child windows. 


Public Functions 
Colors 

Use these members to set and query the color of a specified region of the window. 


backgroundColor 

Returns the background color value of the window area. The default color is returned 
if no color has been set. 


virtual IColor 
backgrounded or () const; 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of the ICanvas class. You cannot copy or assign ICanvas 
objects because both the copy constructor and assignment operator are private functions. 


ICanvas 


ICanvas( unsigned long windowldentitier, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

windowld Window identifier of the canvas you are constructing. 

Note: For OS/2, this value should be limited to the range 0 through 
65535. 

It is recommended that you: 


Supported On: 

PM. Motif 
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Give unique identifiers to all windows in the same frame window. 
"In the same frame window" means that the frame window is the 
first frame in its parent window chain. 



ICanvas 


• Give the client window a window ID of FID_CLIENT (0x8008). 

• Do not use the other FID_xxx values. 

parent The parent window of the canvas you are constructing. You must specify 
a parent window. This constructor throws an IlnvalidParameter exception 
if you pass an IWindow* of 0. 

The parent window is primarily used for visible relationships. 

owner Owner window of the canvas you are constructing. 

Note: In OS/2, the owner window is primarily used for routing 

notification events and unprocessed messages. OS/2 also uses the 
owner window chain to inherit colors. 

In Motif, the owner window is only used for routing unprocessed 
messages. There is no concept of an owner in Motif. 

initial (Optional) The initial position and size of the canvas you are 

constructing. The initial position is the lower-left corner of the canvas 
relative to the lower-left corner of the parent window. 

style (Optional) Specifies the window's characteristics using ICanvas::Styles (p. 

34). 


ICanvas 


virtual 

"ICanvas(); 


Supported On: 

PM, Motif 


Dialog Behavior Support 

Use these members to provide dialog-like keyboard support for the canvas classes. 

defaultPushButton 

Returns the current default push button, if this canvas is in its parent window chain. 
Pressing the Enter key will cause the default push button to be selected. 


virtual IWindowHandl e Supported On: 

defaul tPushButton () const; PM, Motif 

.If the canvas can be tabbed to, true is returned. If any of the canvas's child 

windows can be tabbed to, the canvas can be tabbed to. 
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virtual Boolean Supported On: 

isTabStop() const; PM, Motif 

matchForMnemonic 

Returns the first child window using the specified character as a mnemonic. 


virtual IWi ndowHandle Supported On: 

matchForMnemonic( unsigned short character) const; PM. Motif 

origDefaultButtonHandle 

Returns the push button originally identified as the default. This push button will be 
made the default when the window with the input focus is not a push button. 

Pressing the Enter key will cause the default push button to be selected. 


IWindowHandl e 

origDefaultButtonHandle() const; 


Supported On: 

PM. Motif 


Layout Support 

Layout members determine how this class sizes and positions its child windows or how this 
window will be laid out on another canvas. 


setLayoutDistorted 

Provides notification to a canvas that its layout of child windows needs to be updated. 
All windows maintain an internal state and use setLayoutDistorted to update that state 
and to communicate any changes to the parent window. 

The canvas object uses these state changes to update the size and position of its child 
windows. The internal state of a window is the enumeration IWindow::Layout (Vol. 
II). 

ICanvas::setLayoutDistorted adds the IWindow::layoutDistorted flag to its internal 
state if it receives a value of IWindow::childWindowCreated or 
IWindow::childWindowDestroyed and calls IWindow::setLayoutDistorted. If the 
IWindow::immediateUpdate flag is on, the canvas runs its layout routine. 

virtual ICanvas& Supported On: 

setLayoutDistorted( unsigned long layoutAttributesOn, PM, Motif 

unsigned long 1 ayoutAttributesOff); 
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Style 

Use these members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 
You can use these styles with the styles defined by the following nested class: 

IWindow:: Styles (Vol. II) 

Once you have constructed an ICanvas object, you can use ICanvas and IWindow member 
functions to query and change its style. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

-.Returns the default style. The default style is classDefaultStyle (p. 35) unless you 
have changed the style using setDefaultStyle (p. 31). 

static Style Supported On: 

defaul tStyl e(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent canvases. 

static void Supported On: 

setDefaultStyle( const Style& style); PM, Motif 

style A combination of ICanva::Style (p. 34) and IWindow::Style (Vol. II) 

objects. 


Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 
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INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Constructors 

You can construct and destruct objects of the ICanvas class. You cannot copy or assign ICanvas 
objects because both the copy constructor and assignment operator are private functions. 


ICanvas (); Supported On: 

PM. Motif 

Derived classes that create their own windows should call this ICanvas constructor. 

Event-Handling Implementation 

Event handling implementation members perform processing needed to allow event handlers to 
properly receive and route events. 

passEventToOwner 

Determines whether an event can be passed to the owner window of this canvas. 

virtual Boolean Supported On: 

passEventToOwner( IEvent& event); Motif 

registerCallbacks 

Registers all possible callbacks and X event handlers to this object for events it may 
receive. IHandler derived classes later determine which events they will process. 
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If you override this function in a class derived from ICanvas, your implementation of 
registerCallbacks must call ICanvas::registerCallbacks to register the applicable 
callbacks and X event handlers. 


virtual void Supported On: 

regi sterCall backs (); Motif 

unregisterCallbacks 

Removes callbacks and X events added by registerCallbacks. 

If you override this function in a class derived from ICanvas, your implementation of 
unregisterCallbacks must call ICanvas::unregisterCallbacks for clean-up to occur. 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Layout Support 

Layout members determine how this class sizes and positions its child windows or how this 
window will be laid out on another canvas. 

areChildrenReversed 

States whether the order in which child windows are returned by the class 
IWindow::ChildCursor (Vol. II) matches the order in which the child windows were 
constructed. 

This returns false only if the static function IWindow::setDefaultOrdering is called 
with the enumerator IWindow::onTopOfSiblings and the canvas has not run its layout 
routine. 


Boolean Supported On: 

areChildrenReversed() const; PM. Motif 

calcMinimumSize 

Returns the minimum screen size this control can occupy, based on the size and 
positions of its child windows. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 
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fixupChiidren 

Generates a list of all child windows, determines if any can be tabbed to, and allows 
for reversing the order in which they are iterated. 

virtual IWindowPosBuffer 
fixupChildren(); 

Derived classes use this function to size and position child windows. 

virtual ICanvas& 
layout(); 

_ Returns the size needed to show all child windows. 


ISize 

layoutSize() const; 

setLayoutSize 

Sets the size needed to show all child windows. 


ICanvas& 

setLayoutSize( const ISize& size); 

Supported On: 

PM, Motif 

Inherited Protected Functions 


INotifier 



addObserver 

notifyObservers 

observerList 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
Style 

Use these members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 
You can use these styles with the styles defined by the following nested class: 

IWindow::Styles (Vol. II) 

Once you have constructed an ICanvas object, you can use ICanvas and IWindow member 
functions to query and change its style. 
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classDefaultStyle 

Specifies the original default style for this class, which is IWindow::visible. 


static const Style 
classDefaultStyle; 


Supported On: 

PM, Motif 


Inherited Public Data 


IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundCoIorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

ICanvas contains the following nested classes: 
ICanvas::Style (see page 36) 
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ICanvas "Style 


IBase 
IBitFlag 
ICanvas "Style 


_.None. 

—icanvas.hpp 

The nested class ICanvas::Style provides a set of valid canvas styles for the 
ICanvas::defaultStyle and ICanvas::setDefaultStyle functions, and for the constructor 
of the class ICanvas (p. 27). 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICircularSlider 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

ICircularSlider 


_.None. 

__icslider.hpp 


Member 

Page 

Member 

Page 

Constructor 

41 

proportionalTicks 

46 

armRange 

38 

radius 

38 

buttons 

45 

rotationlncrement 

39 

calcMinimumSize 

44 

setArmRange 

39 

circular Arm 

45 

setDecrementBitmaps 

39 

classDefaultStyle 

45 

setDefaultStyle 

43 

con vertT oGUIS ty le 

43 

setlncrementBitmaps 

39 

defaultStyle 

43 

setRotationlncrement 

40 

display Value 

45 

setTickSpacing 

40 

enableN otification 

42 

setValue 

40 

full360 

45 

tickSpacing 

40 

jumpToPointer 

46 

value 

40 

label 

46 

valueld 

45 

midpoint 

46 

“ICircularSlider 

42 

noTicks 

46 




The ICircularSlider class provides a control to represent a circular slider, which 
allows a user to set, display, or modify a value by rotating the slider arm. The 
circular slider emulates the actual controls of stereo and video components. You can 
use a circular slider to allow users to control the balance, bass, volume, and treble. If 
they click on one of the tick marks, then the circular slider rotates to the new 
position. Or they can grab the slider arm with the mouse and rotate it. The circular 
slider also has plus and minus buttons for moving the slider arm. Use the 
ISliderArmHandler (Vol. II) class to process the events that are generated as the user 
is rotating the circular slider or when the user stops rotating the circular slider. This 
position change event is also generated when the user just clicks on one of the tick 
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marks. And finally, use the IFocusHandler (Vol. II) class to process any focus 
changes. Figure 1 



Volume 


Figure 1. Shows a ICircularSlider with the default styles, the midpoint and circular arm styles 



Balance 


Figure 2. Shows a ICircularSlider with the default styles and proportional ticks style 

IPM You must install the Multimedia Presentation Manager to use ICircularSlider under 
the version 2.1 OS/2 operating system. 


Public Functions 
Arm Operations 

Use these functions to set and query attributesslider arm. They can query and set the arm range, 
the rotational increment, and tick spacing. Also, you can change the increment and decrement 
bitmaps. 


.Returns the range of values over which the arm can be moved. This range contains 

the minimum and maximum value of the circular slider. 

I Range Supported On: 

armRange() const; PM 

Returns the radius of the dial in pixels. This value is indirectly set by sizing the 
control. 
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unsigned long Supported On: 

radius() const; PM 

rotationlncrement 

Returns the increment that the arm is rotated. This is the number by which the 
current value is incremented or decremented when the user selects one of the circular 
slider increment or decrement buttons. 

unsigned long Supported On: 

rotationIncrement() const; PM 


setArmRange 

Sets the range of values over which the arm can be rotated. This range contains the 
minimum and maximum value of the circular slider. The values returned to the 
circular slider are based on the position of the arm inside of this range. If you set a 
range of 0 to 100 and the arm is in the middle, then calling value (p. 40) will return 
50 as the current value. The circular slider supports a minimum value of -32K and a 
maximum value of 32K. 


ICi rcul arSl i der& Supported On: 

setArmRange) const IRange& range); PM 

setDecrementBitmaps 

Sets the bitmaps used for decrement buttons of the circular slider. They are on the 
left hand side of the slider. 


[] ICircularSlider& 

setDecrementBitmaps) const IResourceId& leftllp, 

const IResourceId& leftDown); 

Use this function to load the bitmaps from the resource file. 


Supported On: 

PM 


§ ICi rcul arSlider& Supported On: 

setDecrementBitmaps) const IBitmapHandle& leftUp, PM 

const IBitmapHandle& leftDown); 

Use this function if you have bitmap handles. 

setlncrementBitmaps 

Sets the bitmaps used for increment buttons of the circular slider. They are on the 
right-hand side of the slider. 
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[J ICircularSlider& 

setlncrementBitmaps( const IBitmapHandl e& rightUp, 

const IBitmapHandle& rightDown); 

Use this function if you have bitmap handles. 


Supported On: 

PM 


g ICircularSlider& Supported On: 

setlncrementBi tmaps ( const IResourceId& rightUp, PM 

const IResourceId& rightDown); 

Use this function to load the bitmaps from the resource file. 

setRotationlncrement 

Sets the scroll increment. This is the number by which the current value of the 
circular slider is incremented or decremented when the user selects one of the circular 
slider increment or decrement buttons. 


ICircularSlider& 

setRotation!ncrement( unsigned long increment); 


Supported On: 

PM 


setTickSpacing 

Sets the tick mark increment of the control. This represents the value between the 
tick marks around the circular slider. 

ICircularSlider& Supported On: 

setTickSpacing( unsigned long tick); PM 

.Sets the value of the circular slider. This value must be within the current range. 

The position of the arm is rotated to this value. 

ICircularSlider& Supported On: 

setValue( long value); PM 

..Returns the increment used to draw the tick marks. This represents the value 
between the tick marks around the circular slider. 


unsigned long Supported On: 

tickSpacing() const; PM 

Returns the current value of the circular slider. This value is based on where the 
arm is within the current range. 


long 

value() const; 


Supported On: 

PM 
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Constructors 

You can construct and destruct objects of this class. 

ICircularSlider 

Q ICircularSlider( const IWindowHandl e& handle); Supported On: 

PM 

You can construct an object of this class by specifying a window handle. 
handle The window handle of the circular slider control. 


£ ICi real arSl ider( unsigned long Identifier, Supported On: 

IWindow* parent, PM 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

You can construct objects of this class from an: 


identifier Window identifier of the circular slider you construct. 

It is recommended that you do the following: 

• Assign unique identifiers to all windows in the same frame window. 
"In the same window" means that the frame window is the first 
frame in its parent window chain. 

• Assign the client window a window identifier of 
IC_FRAME_CLIENT_ID. 


parent The parent window of the circular slider you construct. You must specify 
a parent window. This constructor throws an IlnvalidParameter exception 
if you pass an IWindow* of 0. The parent window is primarily used for 
visible relationships. 

owner The owner window of the circular slider you construct. 

initial The initial position and size of the circular slider you construct. The 

initial position is the lower-left corner of the circular slider relative to the 
lower-left corner of the parent window. Optional. 

style Use the styles provided by ICircularSlider Style (p. 44) to specify the 

control’s styles. Optional. 


IPM The window identifier is limited to the range 0 through 65535. The owner window 
is primarily used for routing notification events and unprocessed messages. The OS/2 
operating system also uses the owner window chain to inherit colors. 
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0 ICircularSlider( unsigned long Identifier, 

IWindow* parentAndOwner); 

You can construct objects of this class from an: 

identifier Window identifier of the circular slider you construct. 

It is recommended that you do following: 

• Assign unique identifiers to all windows in the same frame window. 
"In the same window" means that the frame window is the first 
frame in its parent window chain. 

• Assign the client window a window identifier of 
IC_FRAME_CLIENT_ID. 

parentAndOwner 

The parent and owner window of the circular slider you construct. You 
must specify a parent window. This constructor throws an 
IlnvalidParameter exception if you pass an IWindow* of 0. The parent 
window is primarily used for visible relationships. 

IPM The window identifier is limited to the range 0 through 65535. The owner window 
is primarily used for routing notification events and unprocessed messages. The OS/2 
operating system also uses the owner window chain to inherit colors. 


Supported On: 

PM 


"ICircularSlider 


virtual 

~ICircularSlider(); 


Supported On: 

PM 


Observer Notification 

Observer notification members implement the public INotifier protocol for the ICircularSlider 
class. 


enableNotification 

Enables the circular slider control to send notifications to any observer objects. 


virtual ICircularSlider& 
enableNotification( Boolean enable = true); 


Supported On: 

PM 
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Styles 

Use these style members to set and query circular slider styles, the default style for this class, 
and convert the style into a form that is recognizable to the underlying GUI. You can use these 
styles with the styles defined by the following nested classes: 

IWindow Style (Vol. II) 

IControl Style (Vol. II) 


convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

- Returns the current default style. This is the same as classDefaultStyle unless 
setDefaultStyle has been called. 

static Style Supported On: 

defaultStyle(); PM 


setDefaultStyle 

Sets the default style for all subsequent circular sliders. 

static void Supported On: 

setDefaul tStyl e( const Style& style); PM 


Inherited Public Functions 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 
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Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Minimum Size Calculation 

These members are called when the circular slider is put into a canvas. The canvas uses the 
minimum size to calculate how small the circular slider can be when it is displayed. 

calcMinimumSize 

Returns an ISize that indicates the minimum size that the circular slider can be. This 
is used by the ICanvas hierarchy of classes. The minimum size also uses the current 
font and circular slider text in its calculations. 

virtual ISize Supported On: 

calcMinimumSizeO const; PM 


Inherited Protected Functions 



Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
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Notification Members 

This INotificationld string is used for all notifications that ICircularSlider provides to its 
observers. 

...Notification identifier provided to observers when the value of the circular slider 
control changes. ICircularSlider provides the new value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static const INotificationld Supported On: 

valueld; PM 


Styles 

Use these style members to set and query circular slider styles, the default style for this class, 
and convert the style into a form that is recognizable to the underlying GUI. You can use these 
styles with the styles defined by the following nested classes: 

IWindow Style (Vol. II) 

IControl Style (Vol. II) 

Displays increment and decrement buttons. 

static const Style 
buttons; 

—Draws a small circle for the arm, rather than a line. 

static const Style Supported On: 

circularArm; PM 


Supported On: 

PM 


classDefaultStyle 

Specifies the original default style for this class, which is IWindow::visible. 


static const Style Supported On: 

classDefaultStyle; PM 

—Displays the value on the dial. 


static const Style Supported On: 

di spl ayVal ue; PM 

Permits the rotational range to extend 360 degrees. This forces the display Value 
style to be off, which keeps the slider arm from corrupting the number value. 
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static const Style 
ful1360; 


Supported On: 

PM 


jumpToPointer 

Causes the circular slider to change immediately (jump) to the value indicated by the 
position of the mouse. If this style is not present, then the circular slider rotates by 
the rotational increment to the value indicated by the position of the mouse 

static const Style Supported On: 

jumpToPointer; PM 

Displays title text below the dial. 


static const Style Supported On: 

label; PM 

...Makes the midpoint tick mark larger. This tick mark is not visible if the noTicks 
style is set. 


static const Style Supported On: 

midpoint; PM 

Turns off the tick marks. 


static const Style 
noTicks; 


Supported On: 

PM 


proportionalTicks 

Allows the length of the tick marks to be calculated as a percentage of the radius; 
otherwise, they are set to a fixed length. 

static const Style Supported On: 

proportionalTicks; PM 
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IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

ICircularSlider contains the following nested classes: 
ICircularSlider::Style (see page 48) 
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ICircularSlider: :Style 


IBase 

IBitFlag 

ICircularSlider:: Style 


_.None. 

—icslider.hpp 

The nested class ICircularSlider::Style provides a set of valid circular slider styles for 
the defaultStyle and setDefaultStyle functions, and for the constructor of the class 


ICircularSlider (p 

. 37). 


Inherited Public Functions 

IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICircularSliderNotifyHandler 


IBase 

IVBase 

IHandler 

IWindowNotifyHandler 
IT extControlN otify Handler 
ICircularSliderNotifyHandler 


_.None. 

__icsliden.hpp 


Member Page 

Constructor 49 

dispatchHandlerEvent 50 

“ICircularSliderNotifyHandler 50 


Instances of the ICircularSliderNotifyHandler class process events for all classes of 
circular sliders. 


This class is designed to handle events that require the circular slider class to generate 
a notification. If notifications are enabled for this class, a notification will be 
generated and sent to all observers when the proper conditions for the specific 
notification exist. 


Public Functions 
Constructors 

Use these functions to construct and destruct objects of the ICircularSliderNotifyHandler class. 


ICircularSliderNotifyHandler 

Default constructor. 


ICircularSliderNotifyHandler (); 


Supported On: 

PM, Motif 
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~ICircularSliderNotifyHandler 


virtual 

"ICi rcularSliderNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Processing 

Event-processing members evaluate an event to determine if it is appropriate for this handler 
object to process. 

dispatchHandlerEvent 

If any of the following events are received, the circular slider observers are notified: 
• circular slider change event 


virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


ITextControlNotifyHandler 

dispatchHandlerEvent 
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IWindowNotify Handler 

dispatchHandlerEvent 




I Handler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrAllocator 


IBase 

ICnrAllocator 


_.None. 


_icnrobj.hpp 


Member 

Page 

Member 

Page 

Constructor 

52 

nextAvailable 

53 

first 

53 

updateForlnsert 

53 

initialized 

53 

'ICnrAllocator 

53 

next 

53 




ICnrAllocator is a class used to allocate and manage multiple container items that can 
be added to an IContainerControl. ICnrAllocator allows you to create an unlimited 
number of objects at once, then add any number of them to a container with one call. 
This method of allocating and inserting multiple container objects greatly reduces the 
time it takes to load a large number of items into a container. 

As items from the ICnrAllocator are added to an IContainerControl via 
IContainerControl::addObjects or IContainerControl::addObjectsAfter, the 
ICnrAllocator keeps track of all used and unused items it is managing. 

The ICnrAllocator destructor will free the memory occupied by any unused container 
items allocated by the constructor but not added to any IContainerControl. 


Public Functions 
Constructors 

These functions are used to construct and destruct objects of this class. 

... An ICnrAllocator is constructed by providing the number of container items you 
want to allocate and the size of the object you will be adding to an IContainerControl. 

ICnrAllocator( unsigned long num. Supported On: 

unsigned long size); PM 
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ICnr Allocator 


ICnrAllocator 


virtual 

'ICnrAl1ocator(); 


Supported On: 

PM 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Object Information 

These members give access to the objects allocated by ICnrAllocator. 

Returns the first item of the list. 

void* Supported On: 

first() const; PM 

-Returns the number of items initialized. 


unsigned long Supported On: 

initial ized() const; PM 

Returns the next item of the item passed in. 


void* Supported On: 

next( void* pRec); PM 

--Returns the next available item that has not been initialized. 


void* 

nextAvailable(); 


Supported On: 

PM 


updateForlnsert 

Updates the state of an ICnrAllocator object after addObjects or addObjectsAfter is 
called. 
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ICnr Allocator 


ICnrAl 1 ocator& Supported On: 

updateForInsert(); PM 


Inherited Protected Data 
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ICnrBeginEditEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrEditEvent 

ICnrBeginEditEvent 


_.None. 

_.icnreevt.hpp 


Member Page 

Constructor 55 

currentText 56 

“ICnrBeginEditEvent 56 


An ICnrBeginEditEvent is dispatched to ICnrEditHandler::beginEdit when editing 
begins in one of the editable fields of the container. The event provides information 
about the text being edited as well as the type of text (heading, icon, or details view) 
being edited. See ICnrEditHandler::beginEdit (p. 80) for information about that 
function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrBeginEditEvent 

The only way to construct an object of this class is from an IControlEvent object. 
Construct ICnrBeginEditEvent by calling ICnrEditHandler::dispatchHandlerEvent 
from an IControlEvent in response to a request to begin editing. Such an occurrence 
is either as a result of user interaction or under program control. See IControlEvent 
(Vol. II) and ICnrEditHandler::dispatchHandlerEvent (p. 82) for more information. 
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ICnrBeginEditEvent( const IControlEvent& event); 


Supported On: 

PM, Motif Ignored 


"ICnrBeginEditEvent 


virtual 

'ICnrBeginEditEvent (); 


Supported On: 

PM, Motif Ignored 


Event Information 

Use these members to query and set the accessible attributes of this class. 
-. Returns the current text stored in the edit field. 


IString 

currentText(); 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


ICnrEditEvent 

column 

isLeftDetails 

isRightDetailsHeading 

container 

i sLeftDetail sHeading 

isTitleWindow 

isDetailsData 

isRightDetails 

object 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 
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ICnrBeginEditEvent 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


ICnrEditEvent 

textRef 

textS ize 



ICnrEvent 

containerld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrControlList 


ISet 

ICnrControlList 


_.None. 

_icnrclst.hpp 

Member Page 

Constructor 58 

“ICnrControlList 59 


Objects of the ICnrControlList class define a collection of IContainerControl objects. 
The User Interface Class Library uses this class in the implementation of the class 
IContainerControl (p. 163). 

ICnrControlList is derived from the ISet class of the IBM Collection Class Library. 


Public Functions 
Constructors 

Use these functions to construct and destruct objects of this class. 


ICnrControlList 


[J ICnrControl Li st (); Supported On: 

PM, Motif 

The default constructor, which accepts no parameters. 

§ ICnrControl List( const ICnrControl List&); Supported On: 

PM. Motif 

You can construct an object of this class from a pre-existing ICnrControlList object. 
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ICnrControlList 


"ICnrControlList 


virtual 

'ICnrControlList(); 


Supported On: 

PM, Motif 
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ICnrDrawBackgroundEvent 


IBase 

IVBase 

IEvent 

ICnrDrawB ackgroundE vent 


_.None. 

—icnrdiev.hpp 


Member 

Page 

Member 

Page 

Constructor 

60 

itemPresSpaceHandle 

61 

container 

61 

itemRect 

61 

itemld 

61 

'ICnrDrawB ackgroundEvent 

61 


The ICnrDrawBackgroundEvent class provides the information necessary to draw 
objects in the container. This event is not dispatched unless: 

• The IContainerControl::handleDrawItem style is set when the container is created, 
or 

• The IContainerControl::enableDrawItem function is called after construction. 

See IContainerControl::handleDrawItem (p. 211) for information about the 
handleDrawItem style and IContainerControl::enableDrawItem (p. 186) for 
information about that function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrDrawBackgroundEvent 

You can only construct objects of this class from an IEvent object. See IEvent (Vol. 

II) for information about that class. 

ICnrDrawBackgroundEvent( const IEvent& event); Supported On: 

PM, Motif Ignored 
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ICnrDrawBackground Event 


virtual 

"ICnrDrawBackgroundEvent() ; 


Supported On: 

PM, Motif Ignored 


Event Information 

Use these members to query and set the accessible attributes of this class. 
-Returns the container being drawn. 


virtual IContainerControl* 
container() const; 

Returns the item's ID. 


Supported On: 

PM, Motif Ignored 


virtual unsigned long Supported On: 

itemldO const; PM, Motif Ignored 

itemPresSpaceHandle 

Return the item's presentation space handle. 


virtual IPresSpaceHandle Supported On: 

itemPresSpaceHandleQ const; PM, Motif Ignored 

.Returns the rectangle of the item. 


virtual IRectangle 
itemRect() const; 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 
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ICnrDrawBackgroundEvent 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrDrawHandler 


IBase 

IVBase 

IHandler 

ICnrDrawHandler 


-.None. 

_.icnrdihd.hpp 


Member Page 

Constructor 67 

dispatchHandlerEvent 67 

drawBackground 65 

drawDetailsItem 66 

drawlcon 66 

drawText 66 


Member 

Page 

drawTitle 

66 

drawTreelcon 

66 

handleEventsFor 

65 

stopHandlingEventsFor 

65 

“ICnrDrawHandler 

65 


The ICnrDrawHandler class provides the notification of draw item and draw 
background events in the container. 

To dispatch draw item events, you must do either of the following: 

• Specify the IContainerControl::handleDrawItem attribute when you construct the 
container, or 

• Call IContainerControl::enableDrawItem after you construct the container. 

Similarly, to dispatch draw background events, you must: 

• Specify the IContainerControl::handleDrawBackground attribute when you 
construct the container, or 

• Call IContainerControl::enableDrawBackground after you construct the container. 

See IContainerControl: Attributes (p. 208) for information about the handleDrawItem 
and handleDrawBackground container control attributes. Also, see 
IContainerControl::enableDrawItem (p. 186) and 

IContainerControl::enableDrawBackground (p. 186) for information about those 
functions. 
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In addition, whenever you draw a container item or background, call 
IEvent::setResult(true) to prevent the system from drawing the item or background. 
See IEvent::setResult (Vol. II) for information about that function. 

Create a handler derived from ICnrDrawHandler and attach it to the container whose 
foreground or background is to be drawn or to the container's owner window. You 
can do this by calling ICnrDrawHandler: :handleEventsFor to pass the container or 
owner window to the container draw handler. See 

ICnrDrawHandler::handleEventsFor (p. 65) for information about that function. 

ICnrDrawHandler dispatches the following events in the container: 

• Drawing the container background (see ICnrDrawBackgroundEvent) (p. 60) 

• Drawing a details view item, an icon, text, a title, or a tree view icon (see 
ICnrDrawItemEvent) (p. 69) 

Note: Attaching ICnrDrawHandler to a container's owner window does not allow 
you to process ICnrDrawBackgroundEvents. Only ICnrDrawItemEvents are 
processed if ICnrDrawHandler is attached to an owner window. 

When the container draw handler receives one of these container draw events, the 
handler creates a corresponding event object and routes that object to the appropriate 
ICnrDrawHandler virtual function. You must override these virtual functions to 
supply your own specialized processing of a container draw event. 

The return value from the virtual functions specifies whether the container draw event 
should be passed on for additional processing, as follows: 

Return Value Meaning 

true The container draw event requires no additional processing. Do 

not pass it to another handler. 

false Pass the container draw event to the next handler for additional 

processing, as follows: 

• If there is another handler for the container, pass the 
container draw event to the next handler. 

• If this is the last handler for the container, call 
IWindow::defaultProcedure to process 
ICnrDrawBackgroundEvents, and IWindow::dispatch to 
dispatch ICnrDrawItemEvents to the container's owner 
window. 

See IWindow::defaultProcedure (Vol. II) and 
IWindow::dispatch (Vol. II) for information about those 
functions. 
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• If this is the last handler for the container's owner window, 
call IWindow::defaultProcedure to process the 
ICnrDrawItemEvents. The handler should not receive any 
ICnrDrawB ackgroundE vents. 


Public Functions 
Constructors 

You can destruct objects of this class. The only way to construct objects of this class is from a 
derived class. To enforce this, the only constructor we provide for this class is protected. 

"ICnrDrawHandler 


virtual 

"ICnrDrawHandler(); 

Event Dispatching 

These members implement the class. 


handleEventsFor 

Attaches the handler to the specified container control. 

virtual ICnrDrawHandl er& Supported On: 

handleEventsFor( IContai nerControl * container); PM, Motif Ignored 

stopHandlingEventsFor 

Detaches the handler from the specified container control. 

virtual ICnrDrawHandl er& Supported On: 

stopHandl ingEventsFor( IContai nerControl * container); PM, Motif Ignored 

Event Processing 

event-processing members must be supplied by a derived class to provide processing for a draw 
event. 

drawBackground 

Called when the background of the container needs to be redrawn. 


Supported On: 

PM, Motif Ignored 
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virtual Boolean 

drawBackground( ICnrDrawBackgroundEvent& event); 


Supported On: 

PM, Motif Ignored 


drawDetailsItem 

Called in the details view when the data of an object in a column needs to be 
redrawn. The emphasis of the data must be drawn during the processing of this 
event. This is also called when the details view column title needs to be redrawn. In 
this case, a call to ICnrDrawItemEvent::object() will return 0. 


virtual Boolean Supported On: 

drawDetai1sltem( ICnrDrawItemEvent& event); PM, Motif Ignored 

^Called when the icon in the icon or name view needs to be redrawn. The emphasis 
of the icon must be drawn during the processing of this event. 


virtual Boolean Supported On: 

drawIcon( ICnrDrawItemEvent& event); PM, Motif Ignored 

_.Called when the text in the icon, name, or text view needs to be redrawn. The 
emphasis of the text must be drawn during the processing of this event. 


virtual Boolean Supported On: 

drawText( ICnrDrawItemEvent& event); PM, Motif Ignored 

Called when the title of the container needs to be redrawn. 


virtual Boolean 

drawTitle( ICnrDrawItemEvent& event); 


Supported On: 

PM, Motif Ignored 


drawTreelcon 

Called in the tree view when the expanded or collapsed icon needs to be redrawn. 


virtual Boolean 

drawTreelconj ICnrDrawItemEvent& event); 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 
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ICnrDrawHandler 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can destruct objects of this class. The only way to construct objects of this class is from a 
derived class. To enforce this, the only constructor we provide for this class is protected. 

ICnrDrawHandler 

You can only construct instances of this class by using the default constructor, which 
does not accept any arguments. 

ICnrDrawHandler(); Supported On: 

PM, Motif Ignored 


Event Dispatching 

These members implement the class. 

dispatchHandlerEvent 

If a container draw event is found, calls the appropriate virtual function. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif Ignored 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrDrawItemEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

IDrawItemEvent 

ICnrDrawItemEvent 


_.None. 


—icnrdiev.hpp 


Member 

Page 

Constructor 

69 

column 

70 

container 

70 

itemPresSpaceHandle 

70 


Member 

Page 

itemRect 

70 

itemType 

71 

object 

71 

“ICnrDrawItemEvent 

70 


The ICnrDrawItemEvent class provides the information necessary to draw objects in 
the container. This event is not dispatched unless: 

• The IContainerControl::handleDrawItem style is set when the container is created, 
or 

• The IContainerControl::enableDrawItem function is called after construction. 

See Style (p. 210) for information about the handleDrawItem style and 
IContainerControl::enableDrawItem (p. 186) for information about that function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrDrawItemEvent 

You can only construct objects of this class from an IEvent object. See IEvent (Vol. 
II) for information about that class. 
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ICnrDrawItemEvent 


ICnrDrawItemEvent( const IEvent& event); 


Supported On: 

PM, Motif Ignored 


ICnrDrawItemEvent 


virtual 

'ICnrDrawItemEvent(); 


Supported On: 

PM, Motif Ignored 


Event Information 

Use these members to query and set the accessible attributes of this class. 

If an object or column title is being drawn in the details view, the column is 
returned. If the view is other than details view, 0 is returned. 


Supported On: 

PM, Motif Ignored 

Returns the container being drawn. 


virtual IContainerColumn* 
column() const; 


Supported On: 

PM, Motif Ignored 

itemPresSpaceHandle 

Returns the item's presentation space. 


virtual IContainerControl* 
container() const; 


Supported On: 

PM, Motif Ignored 

.Returns the rectangle of the item's size. 


virtual IPresSpaceHandle 
itemPresSpaceHandle() const; 


virtual IRectangle 
itemRect() const; 


Supported On: 

PM, Motif Ignored 
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-Returns the type of the item being drawn. 


virtual ItemType Supported On: 

itemTypeO const; PM, Motif Ignored 

Returns the object in the container being drawn. If the current view is details view 
and the column titles are being drawn, then 0 is returned. 


virtual IContainerObject* 
object() const; 


Supported On: 

PM. Motif Ignored 


Inherited Public Functions 


IDrawItemEvent 

itemld 

itemPresSpaceHandle 

itemRect 


IControIEvent 

controlld 




IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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ICnrDrawItemEvent 


Inherited Protected Functions 


IDrawItemEvent 

ownerltemData 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



ItemType { 

text, icon, treelcon, detailsView, title 

}; 

Enumeration of the possible styles providing the type of the item being drawn: 

text 

The text in all views except the details view. 

icon 

An icon in the icon, name or tree view. 

treelcon 

An expanded or collapsed tree icon. 

detailsView 

Any drawing in the details view. 

title 

The container title. 
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ICnrEditEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrEditEvent 


ICnrBeginEditEvent 

ICnrEndEditEvent 

ICnrReallocStringEvent 


_.icnreevt.hpp 


Member Page 

Constructor 74 

column 74 

container 74 

isDetailsData 74 

isLeftDetails 75 

isLeftDetailsHeading 75 

isRightDetails 75 


Member 

Page 

isRightDetailsHeading 

75 

isTitle Window 

75 

object 

75 

textRef 

76 

textSize 

76 

“ICnrEditEvent 

74 


The ICnrEditEvent class forms the base of the container edit events. These events are 
dispatched during direct editing in the container. Editing can be started by the user or 
by program control using the following functions: 

IContainerControl::editObject (p. 183) 

IContainerControl::editColumnTitle (p. 183) 

IContainerControl::editContainerTitle) (p. 183) 

Direct editing of a field in the container is not allowed unless the field is set to 
"editable". Whether the container is editable is controlled by the following styles: 

IContainerControl::Style::readOnly (p. 210) 

IContainerColumn::Style::readOnly (p. 158) 
IContainerColumn::Style::readOnlyHeading (p. 158) 

and the following functions: 

IContainerObject::enableDataUpdate (p. 246) 
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IContainerObject: :disableDataUpdate (p. 246) 

The ICnrEditEvent class and its subclasses provide information describing the 
location in the container being edited as well as describing the contents of the data 
being edited. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

ICnrEditEvent 

You can only construct objects of this class from an IControlEvent object. See 
IControlEvent (Vol. II) for information about that class. 

ICnrEditEvent ( const IControlEvent& event); Supported On: 

PM, Motif Ignored 


"ICnrEditEvent 


virtual 

'ICnrEditEventO ; 


Supported On: 

PM, Motif Ignored 


Event Information 

Use these members to query and set the accessible attributes of this class. 

Returns the column being edited. If the edit is not column-related (for example, a 
title edit), 0 is returned. 


Supported On: 

PM, Motif Ignored 

Returns the container in which the edit is taking place. 


virtual IContainerColumn* 
column() const; 


virtual IContainerControl* Supported On: 

contained) const; PM, Motif Ignored 

_If data in a column of the details view is being edited, true is returned. 


Boolean 

isDetailsData() const; 


Supported On: 

PM, Motif Ignored 
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_If data in the left column of the details view is being edited, true is returned. 


Supported On: 

PM, Motif Ignored 

isLeftDetailsHeading 

If the left details heading is being edited, true is returned. 


Boolean 

isLeftDetai1s() const; 


Boolean 

isLeftDetailsHeading() const; 


Supported On: 

PM, Motif Ignored 


isRightDetails 

If data in the right column of the details view is being edited, true is returned. 


Boolean Supported On: 

isRightDetai 1 s() const; PM, Motif Ignored 

isRightDetailsHeading 

If the right details heading is being edited, true is returned. 

Boolean 

isRightDetailsHeading() const; 

isTitleWindow 

If the title is being edited, true is returned. 

Boolean Supported On: 

isTitleWindowO const; PM, Motif Ignored 

Returns the object being edited. If the edit is not object-related (for example, a title 
edit), 0 is returned. 


Supported On: 

PM, Motif Ignored 


virtual IContainerObject* 
object() const; 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


IControlEvent 

controlld 
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IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Text 

These members implement the class. 

Returns a pointer to the current text pointer for the ICnrBeginEditEvent and 
ICnrReallocStringEvent events. For ICnrEndEditEvent, a pointer to the new text 
pointer is returned. 

See ICnrBeginEditEvent (p. 55), ICnrReallocStringEvent (p. 112), and 
ICnrEndEditEvent (p. 86) for information about those classes. 

char ** Supported On: 

textRef() const; PM, Motif Ignored 

Returns the number of bytes in the text string (not counting the NULL termination) 
for ICnrEndEditEvent and ICnrReallocStringEvent events. Otherwise, 0 is returned. 

See ICnrEndEditEvent (p. 86) and ICnrReallocStringEvent (p. 112) for information 
about those classes. 

unsigned long Supported On: 

textSizeQ const; PM, Motif Ignored 
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ICnrEditEvent 


Inherited Protected Functions 



Inherited Protected Data 
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ICnrEditHandler 


IBase 

IVBase 

IHandler 

ICnrEditHandler 


_.None. 

_icnrehdr.hpp 


Member Page 

Constructor 79 

beginEdit 80 

dispatchHandlerEvent 82 

endEdit 80 

handleEventsFor 80 

isDatalString 80 


Member 

Page 

mleHandler 

81 

multiLineEdit 

81 

reallocateString 

80 

setMLEHandler 

81 

stopHandlingEventsFor 

80 

"ICnrEditHandler 

79 


The ICnrEditHandler class supports direct editing of data in the container. 

Create a handler derived from ICnrEditHandler and attach it to the container whose 
data is to be edited. You can do this by calling ICnrEditHandler: :handleEventsFor (p. 
80) to pass the container or the container's owner window to the container edit 
handler. 

ICnrEditHandler dispatches the following events in the container: 

• Begin direct editing (see ICnrBeginEditEvent) (p. 55) 

• End direct editing (see ICnrEndEditEvent) (p. 86) 

• Reallocate storage for edited data (see ICnrReallocStringEvent) (p. 112) 

When the container edit handler receives one of these container edit events, it creates 
a corresponding event object and routes that object to the appropriate ICnrEditHandler 
virtual function. You must override these virtual functions to supply your own 
specialized processing of a container edit event. 

The return value from the virtual functions specifies whether the container edit event 
should be passed on for additional processing, as follows: 
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Return Value Meaning 

true The container edit event requires no additional processing. Do 

not pass it to another handler. 

false Pass the container edit event to the next handler for additional 

processing, as follows: 

• If there is another handler for the container, pass the 
container edit event to the next handler. 

• If this is the last handler for the container, call 
IWindow::dispatch (Vol. II) to dispatch the container edit 
event to the container's owner window. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (Vol. II) to process the 
container edit event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

ICnrEditHandler 

You can only construct instances of this class by providing the type of the user data 
that needs to be edited. The data can be one of the types specified by the StringType 
(p. 82) enumeration. 

The default behavior of this class provides for the reallocation of the user data. The 
default behavior of this class also manages the allocation of other types of editable 
data, such as: 

Icon text 
Container title 

Details view column headings 

ICnrEditHandler( StringType StringType = isIString); Supported On: 

PM, Motif Ignored 


"ICnrEditHandler 

virtual 

"ICnrEditHandler(); 


Supported On: 

PM, Motif Ignored 
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Event Dispatching 

These members implement the class. 

handleEventsFor 

Attaches the handler to the specified container control. 


virtual ICnrEditHandler& 
handleEventsFor( IContainerControl* container); 


Supported On: 

PM, Motif Ignored 


stopHandlingEventsFor 

Detaches the handler from the specified container control. 

virtual ICnrEditHandl er& Supported On: 

stopHandl i ngEventsFor( IContainerControl* container); PM. Motif Ignored 


Event Processing 

Event-processing members must be supplied by a derived class to provide processing for an edit 
event. 


.Called when an edit window has been opened in the container. The default behavior 

creates an IMultiLineEdit (Vol. II) object by calling multiLineEdit (p. 81). If 
setMLEHandler (p. 81) has been previously called to store an edit handler, the 
handler is added to the multi-line entry field control. 


virtual Boolean Supported On: 

beginEdit( ICnrBeginEditEvent& event); PM, Motif Ignored 

.Called when editing has ended. This is received after reallocateString (p. 80) is 
called. 


Supported On: 

PM, Motif Ignored 

_If the user data is type IString (Vol. I), true is returned. 


virtual Boolean 

endEdit( ICnrEndEditEvent& event); 


Boolean 

isDataIString() const; 


Supported On: 

PM, Motif Ignored 


reallocateString 

Called when text has been modified in the container and storage needs to be 
reallocated. If the data is an IString (Vol. I), the reallocation is provided by calling 
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ICnrReallocStringEvent::reallocateString (p. 113). If the data is of the type 
isCharacterPointer, the reallocation is provided by calling 
ICnrReallocStringEvent::reallocateText (p. 113). 

virtual Boolean Supported On: 

reallocateString( ICnrReal1ocStringEvent& event); PM, Motif Ignored 


Multiple-Line Edit Processing 

Use these members to enable processing of events to the container's edit field. 

-..Called to return the handler for a multi-line entry field. If a handler has not been 
provided, 0 is returned. 


IHandler* Supported On: 

ml eHandl er() const; PM, Motif Ignored 

—Called to return an IMultiLineEdit (Vol. II) "wrapper" You can override this 
function to specialize the edit control. 


virtual IMultiLineEdit* Supported On: 

multi Li neEdit( const IWindowHandle& handl eMul ti Li neEdi t); PM, Motif Ignored 


setMLEHandler 

Stores a handler to be added to the multi-line entry field control when that control is 
created. 


virtual void 

setMLEHandler( IHandler* anMLEHandler); 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

These members implement the class. 

dispatchHandlerEvent 

If a container edit event is found, calls the appropriate virtual function. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif Ignored 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



StringType { 
isIString, 
isCharacterPointer 
}; 


Enumeration identifying the real type of user data in the details view of the container: 

isIString 

The data is an IString (Vol. I) object. 

isCharacterPointer 

The data is a pointer to a character (char*). 
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ICnrEmphasisEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrEmphasisEvent 


_.None. 


__icnrevt.hpp 
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Objects of the ICnrEmphasisEvent class are dispatched whenever the container 
record's attributes are changed. These events are created in response to a 
change-in-emphasis notification from the container. Emphasis is a visible indication 
of the condition of an object that can affect the ability of a user to interact with that 
object. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrEmphasisEvent 

Although you can construct objects of this class, typically 

ICnrHandler::dispatchHandlerEvent (p. 99) creates objects of this class from an object 
of the class IControlEvent (Vol. II) in response to a change-in-emphasis notification 
from the container. 

Q ICnrEmphasisEvent ( const IControl Event& event); Supported On: 

PM, Motif 
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g ICnrEmphasisEvent( IControlEvent& event, Supported On: 

IContainerObject* object, Motif 

Boolean acquiring); 


ICnrEmphasisEvent 


virtual 

"TCnrEmphasisEvent (); 


Supported On: 

PM, Motif 


Event Information 

Use these members to query and set the accessible attributes of this class. 
_If the specified emphasis value has changed, true is returned. 


Boolean Supported On: 

changed( IContainerObject: :Emphasis emphasis) const; PM, Motif 

_.Returns true if the ICnrEmphasisEvent is for an object that is acquiring emphasis. 
Otherwise, it returns false. The ICnrHandler::selectedChanged function uses this 
function. 


Boolean Supported On: 

isAcquired() const; Motif 

Returns the object that has changed its emphasis. 


IContainerObject* 
object() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 
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IEvent 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


ICnrEvent 

containerld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrEndEditEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrEditEvent 

ICnrEndEditEvent 


_.None. 

_.icnreevt.hpp 
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An ICnrEndEditEvent is dispatched to ICnrEditHandler::endEdit (p. 80) when text 
editing is complete. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrEndEditEvent 

You can only construct objects of this class from an IControlEvent (Vol. II) object. 
Construct ICnrEndEditEvent by calling ICnrEditHandler::dispatchHandlerEvent (p. 

82) from an IControlEvent in response to a notification from the container that direct 
editing has ended. Such an occurrence is either as a result of user interaction or 
under program control. 

ICnrEndEditEvent ( const IControl Event& evt); Supported On: 

PM, Motif Ignored 
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"ICnrEndEditEvent 


virtual 

'ICnrEndEditEventO ; 


Supported On: 

PM, Motif Ignored 


Event Information 

use these members to query and set the accessible attributes of this class. 

_ Returns the current text stored in the container. 

If ICnrReallocStringEvent::reallocateString (p. 113) returns true, indicating that the 
text was reallocated, the returned text is the text entered by the user in the edit field. 

If ICnrReallocStringEvent::reallocateString returns false, indicating that the text was 
not reallocated, the returned text is the text that was in the edit field before editing 
began. 


IString Supported On: 

currentTextQ; PM, Motif Ignored 

Returns the text the user entered in the edit field. 


IString Supported On: 

newTextQ ; PM. Motif Ignored 


Inherited Public Functions 


ICnrEditEvent 

column 

isLeftDetails 

isRightDetailsHeading 

container 

isLeftDetailsHeading 

isTitleWindow 

isDetailsData 

isRightDetails 

object 


IControIEvent 

controlld 




IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 
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ICnrEndEditEvent 


IE vent 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


ICnrEditEvent 

textRef 

textS ize 



ICnrEvent 

containerld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrEnterEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrEnterEvent 


_.None. 


__icnrevt.hpp 
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Objects of the ICnrEnterEvent class are dispatched when an enter event occurs in the 
container. This can be as a result of the following: 

• The Enter key 

• A double click of the mouse select button 

These events are created in response to an enter notification from the container. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrEnterEvent 

Although you can construct objects of this class, typically 

ICnrHandler::dispatchHandlerEvent (p. 99) creates objects of this class from an object 
of the class IControlEvent (Vol. II) in response to the user pressing the Enter key or 
double-clicking the mouse select button. 

ICnrEnterEvent( const IControlEvents event); Supported On: 

PM, Motif 
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"ICnrEnterEvent 


virtual 

'ICnrEnterEvent (); 


Supported On: 

PM, Motif 


Event Information 

Use these members to query and set the accessible attributes of this class. 

_„If the event is the result of pressing the keyboard Enter key, true is returned. 
Otherwise, the event occurred because the select button was double clicked. 


Boolean Supported On: 

enterPressed() const; PM. Motif 

Returns the object over which the enter occurred. If the enter did not occur on an 
object, 0 is returned. 


IContainerObject* Supported On: 

object() const; PM. Motif 

_If the event occurred over an object, true is returned. 


Boolean 

val idObject () const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 
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IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


ICnrEvent 

containerld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



© IBM Corp. 1992, 1995 


ICnrEnterEvent 91 






ICnrEvent 



ICnrEvent 


IBase 

IVBase 

IEvent 


ICnrHelpEvent 

ICnrQueryDeltaEvent 

ICnrScrollEvent 


Member 

Page 

Constructor 

92 

containerld 

93 

'ICnrEvent 

93 


IControlEvent 

ICnrEvent 


ICnrEditEvent 

ICnrEmphasisEvent 

ICnrEnterEvent 


—icnrevt.hpp 


ICnrEvent is the base class for all container events classes. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

-Although you can construct objects of this class, typically 

ICnrHandler::dispatchHandlerEvent (p. 99) creates objects of this class from an object 
of the class IControlEvent (Vol. II) in response to the user pressing the Enter key or 
double-clicking the mouse select button. 

ICnrEvent ( const IControl Event& event); Supported On: 

PM, Motif 
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ICnrEvent 


"ICnrEvent 


virtual 

'ICnrEvent (); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IControIEvent 

controlld 




IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Information 

These members implement the class. 

_ Returns the control ID for the container. 


unsigned long 
containerId() const; 


Supported On: 

PM, Motif 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrHandler 


IBase 

IVBase 

IHandler 

ICnrHandler 


_.None. 


_icnrhdr.hpp 


Member 
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96 
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97 
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97 
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99 
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97 

handleEventsFor 

96 
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97 


Member 
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inuseChanged 

97 

selectedChanged 

98 
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97 
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98 

treeExpanded 

98 

windowScrolled 

98 

“ICnrHandler 

96 


Objects of the ICnrHandler class provide basic event handling capability for the 
container. 

Create a handler derived from ICnrHandler and attach it to the container whose 
events are to be handled. You can do this by calling handleEventsFor (p. 96) to pass 
the container to the container handler. 

ICnrHandler dispatches the following events in the container: 

• Changing selection, in-use, or cursored emphasis for an object in the container. 
This is described in ICnrEmphasisEvent (p. 83). 

• Scrolling past the container’s delta value. This is described in 
ICnrQueryDeltaEvent (p. 109). 

• Responding to an enter event using the keyboard or mouse. This is described in 
ICnrEnterEvent (p. 89). 

• Requesting help in the container. This is described in ICnrHelpEvent (p. 100). 

• Expanding and collapsing nodes in a tree view. This is described in 
IContainerObject (p. 241). 
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• Scrolling the container window. This is described in ICnrScrollEvent (p. 116). 

When the container handler receives one of these events, it creates a corresponding 
event object and routes that object to the appropriate ICnrHandler virtual function. 
You must override these virtual functions to supply your own specialized processing 
of these events. 

The return value from the virtual functions specifies whether the event is passed on 
for additional processing, as follows: 

true The event requires no additional processing. Do not pass it to another 
handler. 

false If there is another handler for the container, pass the event to the next 
handler. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

_ You can only construct objects of this class by using the default constructor, which 
does not accept any parameters. 

ICnrHandl er(); Supported On: 

PM, Motif 


"ICnrHandler 


virtual 

"'ICnrHandl er(); 


Supported On: 

PM. Motif 


Event Dispatching 

These members implement the class. 


handleEventsFor 

Attaches the handler to the specified container control. 


virtual ICnrHandler& 

handleEventsFor( IContainerControl* container); 


Supported On: 

PM. Motif 
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stopHandlingEventsFor 

Detaches the handler from the specified container control. 


virtual ICnrHandler& 

stopHandlingEventsFor( IContainerControl* container); 


Supported On: 

PM, Motif 


Event Processing 

Event-processing members must be supplied by a derived class to provide processing for an edit 
event. 


cursoredChanged 

Called when the cursored emphasis of an object changes. By default, this function 
calls IContainerObject::handleCursoredChange (p. 243) on the object whose emphasis 
has changed. 


virtual Boolean 

cursoredChanged( ICnrEmphasi sEvent& event); 


Supported On: 

PM, Motif Ignored 


deltaReached 

Called when the container is scrolled to the predefined delta. 

virtual Boolean Supported On: 

deltaReached( ICnrQueryDeltaEvent& event); PM, Motif Ignored 

Called when the user selects the Enter key or double-clicks the mouse select button 
on an object. If the enter occurs over an object, by default, this function calls 
IContainerObject::handleOpen (p. 244). Otherwise, this function ignores the enter. 

virtual Boolean Supported On: 

enter( ICnrEnterEvent& event); PM, Motif 

.Called when help is requested in a container. 

virtual Boolean Supported On: 

hel p ( ICnrHel pEvent& event); PM, Motif 

| Motif By default, this function does nothing. 

inuseChanged 

Called when the in-use emphasis of an object changes. By default, this function calls 
IContainerObject::handleInuseChange (p. 244). 
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virtual Boolean 

inuseChanged( ICnrEmphasisEvent& event); 


Supported On: 

PM, Motif Ignored 


selectedChanged 

Called when the selection emphasis of an object changes. By default, this function 
calls IContainerObject::handleSelectedChange (p. 244). 


virtual Boolean 

selectedChanged( ICnrEmphasisEvent& event); 


Supported On: 

PM. Motif 


treeCollapsed 

Called when the specified object is collapsed in the specified container. By default, 
this function calls IContainerObject::handleTreeCollapse (p. 244). 


virtual Boolean 

treeCollapsed( IContainerObject* collapsedObject, 
IContainerControl* container); 


Supported On: 

PM. Motif 


treeExpanded 

Called when the specified object is expanded in the specified container. By default, 
this function calls IContainerObject::handleTreeExpand (p. 244) on the expanded 
object. 


virtual Boolean 

treeExpanded( IContainerObject* expandedObject, 
IContainerControl* container); 


Supported On: 

PM. Motif 


windowScrolled 

Called when the container window is scrolled. 


Supported On: 

PM, Motif Ignored 

IMotifl By default, this function does nothing. 


virtual Boolean 

windowScrolled( ICnrScrol 1 Event& event); 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 
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IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

These members implement the class. 


dispatchHandlerEvent 

If a container event is received, the appropriate virtual function is called. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



© IBM Corp. 1992, 1995 


ICnrHandler 99 







ICnrHelpEvent 



ICnrHelpEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrHelpEvent 


_.None. 


_ icnrevt.hpp 
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Objects of the ICnrHelpEvent class are dispatched when a user requests help in the 
container. These events are created in response to a notification from the container 
that the user has requested help. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrHelpEvent 

Although you can construct objects of this class, typically 

ICnrHandler::dispatchHandlerEvent (p. 99) creates objects of this class from an object 
of the class IControlEvent (Vol. II) in response to a notification from the container 
that the user has requested help. 

ICnrHelpEvent ( const IControl Event& event); Supported On: 

PM, Motif 
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"ICnrHelpEvent 


virtual 

'ICnrHelpEvent (); 


Supported On: 

PM, Motif 


Event Information 

Use these members to query and set the accessible attributes of this class. 

, If help was requested within a multiple-line edit field, the column being edited is 
returned. Otherwise, 0 is returned. 


IContai nerCol umn* Supported On: 

column() const; PM, Motif 

Returns the object over which help is requested. Otherwise, it returns 0. 


IContainerObject* Supported On: 

objectO const; PM, Motif 


Inherited Public Functions 


IControIEvent 

controlld 




IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 
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IBase 

asString 

messageText 

version 


Inherited Protected Functions 


ICnrEvent 

containerld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrMenuHandler 


IBase 

IVBase 

IHandler 

IMenuHandler 

ICnrMenuHandler 


_.None. 

_ icnrmhdr.hpp 
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Objects of the ICnrMenuHandler class extend the class IMenuHandler (Vol. II) by 
providing specific information related to the menu. Primarily, this means providing 
the object over which the menu was requested. 

Create a handler derived from ICnrMenuHandler and attach it to the container whose 
menu events are to be handled. You can do this by calling handleEventsFor (p. 104) 
to pass the appropriate container to the container menu handler. 

When the container menu handler receives a container menu event, it creates an 
IMenuEvent (Vol. II) object and routes that object to the appropriate 
ICnrMenuHandler virtual function. You must override these virtual functions to 
supply your own specialized processing of a container menu event. 

The return value from the virtual functions specifies whether the container menu 
event is passed on for additional processing, as follows: 

true The container menu event requires no additional processing. Do not pass it 
to another handler. 

false If there is another handler for the container, pass the container menu event 
to the next handler. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 


"ICnrMenuHandler 


virtual 

"TCnrMenuHandl er(); 


Supported On: 

PM. Motif 


Event Dispatching 

These members are overridden to implement the class. 

handleEventsFor 

Attaches the handler to the specified container control. 

Note: This handler cannot be attached to IWindow*. and the inherited function for 
doing so is private. 


virtual ICnrMenuHandler& Supported On: 

handleEventsFor( IContainerControl* container); PM. Motif 

stopHandlingEventsFor 

Detaches the handler from the specified container control. 

virtual ICnrMenuHandl er& Supported On: 

stopHandl i ngEventsFor( IContainerControl* container); PM. Motif 


Event Information 

Use these members to query and set the accessible attributes of this class. 


popupMenuObject 

Returns the object for which a pop-up menu was requested. If a pop-up menu was 
not requested for an object, 0 is returned. 


IContainerObject* 
popupMenuObject(); 


Supported On: 

PM. Motif 
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Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. 

ICnrMenuHandler 

You can only construct objects of this class by using the default constructor, which 
does not accept any parameters. 

ICnrMenuHandler(); Supported On: 

PM, Motif 


Event Dispatching 

These members are overridden to implement the class. 


addSourceEmphasis 

Adds source emphasis by calling IContainerControl::showSourceEmphasis (p. 203). 
Note: A different overload of the same function is called. 

• If the object is not selected, source emphasis is displayed on the object. 

• If the object is selected and other objects are also selected, source emphasis is 
displayed on the group of objects. 

• If a pop-up menu is selected off of an object, source emphasis is displayed on the 
container itself. 
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virtual void Supported On: 

addSourceEmphasi s ( const IMenuEvent& menuEvent); PM, Motif Ignored 

dispatchHandlerEvent 

If a container menu event is received, the appropriate virtual function is called. 


virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM, Motif 

—Resets the pointer to the menu object that is stored when the menu is created, and 
calls IMenuHandler::menuEnded (Vol. II) to complete the processing. 


virtual Boolean Supported On: 

menuEnded( IMenuEvent& menuEvent); PM, Motif 

removeSourceEmphasis 

Removes source emphasis by calling IContainerControl::hideSourceEmphasis (p. 201). 

This function reverses the action of addSourceEmphasis. 

Note: A different overload of the same function is called. 


virtual void Supported On: 

removeSourceEmphasis( const IMenuEvent& menuEvent); PM, Motif Ignored 


Inherited Protected Functions 


IMenuHandler 

addSourceEmphasis 

makePopUpMenu 

menuSelected 

dispatchHandlerEvent 

menuEnded 

menuShowing 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrObjectSet 


ISequence 

ICnrObjectSet 


_.None. 

_ icnrolst.hpp 

Page 

107 

108 


Member 

Constructor 

"ICnrObjectSet 


Objects of the ICnrObjectSet class define a set of IContainerObjects (p. 241). 
IContainerControl (p. 163) provides several functions that return sets of 
IContainerObjects. 

ICnrObjectSet is derived from the ISequence class of the IBM Collection Class 
Library. 


Public Functions 
Constructors 

Use these functions to construct and destruct objects of this class. 


ICnrObjectSet 


Q ICnrObjectSet(); Supported On: 

PM. Motif 

The default constructor, which accepts no parameters. 

£ ICnrObjectSet( const ICnrObjectSet&); Supported On: 

PM, Motif 

You can construct an object of this class from a pre-existing ICnrObjectSet object. 
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"ICnrObjectSet 


virtual 

'ICnrObjectSetO; 


Supported On: 

PM, Motif 
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IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrQueryDeltaEvent 


_.None. 

__icnrevt.hpp 
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Objects of the ICnrQueryDeltaEvent class are dispatched when the delta value is 
reached in the container. These events are created in response to a notification from 
the container that the pre-set delta value has been reached. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrQueryDeltaEvent 

Although you can construct objects of this class, typically 

ICnrHandler::dispatchHandlerEvent (p. 99) creates objects of this class from an object 
of the class IControlEvent (Vol. II) in response to a notification from the container 
that the pre-set delta value has been reached. 

ICnrQueryDeltaEvent ( const IControl Event& event); Supported On: 

PM, Motif Ignored 
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ICnrQueryDeltaEvent 


virtual 

'ICnrQueryDeltaEventO; 


Supported On: 

PM, Motif Ignored 


Event Information 

Use these members to query and set the accessible attributes of this class. 


at Bottom Delta 

If the object that represents the delta value scrolls into view at the bottom of the 
container, true is returned. 


Boolean Supported On: 

atBottomDeltaO const; PM, Motif Ignored 

„If the container has scrolled to the first object in the container, true is returned. 


Boolean Supported On: 

atFi rstObjectO const; PM, Motif Ignored 

_If the container has scrolled to the last object in the container, true is returned. 


Boolean Supported On: 

atLastObject() const; PM, Motif Ignored 

„If the object that represents the delta value scrolls into view at the top of the client 
area, true is returned. 


Boolean 

atfopDelta() const; 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 
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IEvent 

di spatching W indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


ICnrEvent 

containerld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrReallocStringEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrEditEvent 

ICnrReallocStringEvent 


_.None. 


_.icnreevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

112 

reallocateString 

113 

currentText 

113 

reallocateText 

113 

newText 

113 

'ICnrReallocStringEvent 

113 

newTextSize 

113 




An ICnrReallocStringEvent is dispatched to ICnrEditHandler::reallocateString (p. 80) 
when text is edited in the container and it is necessary to reallocate the storage for the 
text. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrReallocStringEvent 

You can only construct objects of this class from an IControlEvent (Vol. II) object. 
Construct ICnrReallocStringEvent by calling ICnrEditHandler::d i spatch HandIerEvent 
(p. 82) from an IControlEvent in response to a notification from the container that 
text has changed and storage for the text may need to be reallocated. 

ICnrReal locStringEvent( const IControlEvent& event); Supported On: 

PM, Motif Ignored 
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"ICnrReallocStringEvent 


virtual 

'ICnrReal locStringEvent(); 


Supported On: 

PM, Motif Ignored 


Event Information 

Use these members to query and set the accessible attributes of this class. 
_ Returns the current text stored in the edit field. 


virtual IString 
currentText() const; 

Returns the text the user added to the edit control. 


Supported On: 

PM, Motif Ignored 


virtual IString Supported On: 

newTextQ const; PM, Motif Ignored 

__Returns the size (not counting the NULL termination) of the storage that needs to 
be allocated to store the new text string. 


long 

newTextSize() const; 


Supported On: 

PM, Motif Ignored 


Text Allocation 

These members reallocate the storage for the text field. 


reallocateString 

Creates and stores an IString (Vol. I) of the appropriate size to hold the new data. 


void 

reallocateString(); 


Supported On: 

PM, Motif Ignored 


reallocateText 

Calls global operator new to acquire storage of the appropriate size to hold the new 
data. 


void 

real 1ocateText (); 


Supported On: 

PM, Motif Ignored 
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Inherited Public Functions 


ICnrEditEvent 

column 

isLeftDetails 

isRightDetailsHeading 

container 

i sLeftDetail sHeading 

isTitleWindow 

isDetailsData 

isRightDetails 

object 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


ICnrEditEvent 

textRef 

textS ize 



ICnrEvent 

containerld 




114 Open Class Library Reference 








ICnrReallocStringEvent 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICnrScrollEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

ICnrEvent 

ICnrScrollEvent 


_.None. 


_ icnrevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

116 

isRightDetails 

117 

amount 

117 

is Vertical 

117 

isHorizontal 

117 

"ICnrScrollEvent 

117 

isLeftDetails 

117 




Objects of the ICnrScrollEvent class are dispatched when scrolling is requested in the 
container. These events are created in response to a notification from the container 
that one of the container's windows has been scrolled. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICnrScrollEvent 

Although you can construct objects of this class, typically 

ICnrHandler::dispatchHandlerEvent (p. 99) creates objects of this class from an object 
of the class IControlEvent (Vol. II) in response to a notification from the container 
that one of the container's windows has been scrolled. 

ICnrScrol 1 Event( const IControlEvent& event); Supported On: 

PM, Motif Ignored 
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"ICnrScrollEvent 


virtual 

'ICnrScrol1Event(); 


Supported On: 

PM, Motif Ignored 


Event Information 

Use these members to query and set the accessible attributes of this class. 
Returns the amount the window has scrolled, in pixels. 


long 

amount() const; 

_lf scrolling in the horizontal direction, true is returned. 


Supported On: 

PM, Motif Ignored 


Boolean Supported On: 

i sHorizontal () const; PM, Motif Ignored 

_If the scrolling occurred in the left (or only) side of the details view, true is 
returned. 


Boolean 

isLeftDetai1s() const; 


Supported On: 

PM, Motif Ignored 


isRightDetails 

If the scrolling occurred in the right side of a split details view, true is returned. 


Boolean Supported On: 

i sRi ghtDetai 1 s () const; PM, Motif Ignored 

.If scrolling occurred in the vertical direction, true is returned. 


Boolean 

isVertical () const; 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


IControIEvent 

controlld 
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IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


ICnrEvent 

containerld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICollectionViewComboBox 


IBase 
IVBase 
INotifier 
IWindow 
IControl 
ITextControl 
IEntryField 
IBaseComboBox 
ICollectionV iewComboB ox 


_.None. 


„ icombo v w .hpp 


Member 

Page 

Constructor 

123 

collectionReplaced 

121 

deselect 

124 

elementAdded 

121 

elementChanged 

122 

elementDeleted 

122 

elementsChanged 

122 

itemChangedld 

128 

items 

120 


Member 

Page 

itemsld 

128 

noSelection 

129 

select 

124 

selectedCollectionPosition 

125 

selectedElement 

125 

setltems 

120 

setStringGenerator 

125 

stringGenerator 

126 

“ICollectionV iewComboBox 

124 


The ICollectionViewComboBox<Element, Collection> template class provides a view 
of an ordered collection, as items in the list box portion of a combination box. 
Template class Element is the type of objects in the collection, and template class 
Collection is the type of collection. The sequence of elements is the same between the 
ordered collection and list box portion of the combination box. The 
ICollectionViewComboBox interface consists of the following: 

• Population and query members for accessing the collection 

• Collection-reporting protocol for receiving and handling collection updates 

• String generator for translating elements to IStrings 

• Selection members 

• Notification members 

The setltems member populates the list box portion of the combination box from 
collection elements. The items member returns the collection being viewed. 
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The collection-reporting protocol refers to the virtual member functions such as 
elementsChanged, that handle repotted changes in the observed collection. The 
ICollectionViewComboBox object observes the currently viewed collection (initialized 
on setltems) and reports collection updates via calls to the collection-reporting 
members. Then the collection-reporting members update the list box portion of the 
combination box. 

The string generator object translates collection elements to their IString 
representations. The default string generator assumes the collection elements natively 
support operators or are Object* objects, where Object has an asString member 
function. The collection-reporting members use this string generation mechanism in 
their processing. 

The selection members query and manipulate the selection state of the list box portion 
of the combination box based on collection elements. This includes the following: 

• Selecting or deselecting based on an item's collection position 

• Querying what collection element corresponds to the item selected in the list box 
portion of the combination box. 

An ICollectionViewComboBox object sends notifications, so observers of the object 
can monitor the following events, and process as needed: 

• The viewed collection is replaced. 

• An item changes in the list box portion of the combination box (due to an update 
of the corresponding collection element). 


Public Functions 


Collection 

Use these members to set and retrieve the collection currently being viewed by the 
ICollectionViewComboBox object. 

Returns the collection currently being viewed. Use it to access the underlying 
collection. 


virtual Collection* Supported On: 

iterns() const; PM 

_ Changes the underlying viewed collection for the combination box. Effectively, this 
repopulates the list box portion of the combination box with items corresponding to 
the elements in the new collection. This is the only direct way to populate the list box 
portion of an ICollectionViewComboBox object. All other changes to items in the 
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list box portion of the combination box result from changes to the underlying 
collection elements reported via the collection-reporting protocol. 

collection A pointer to a collection. ICollectionViewComboBox supports collections 
that are descendents of IPartOrderedCollection. 


virtual ICollectionViewComboBox <Element, Collection^ 
setltems( Collection* collection); 


Supported On: 

PM 


Collection-Reporting Protocol 

Use these members to handle reported changes in the underlying ordered collection. As a set, 
they are a protocol through which changes in the collection are repotted and subsequently 
processed via updates to the control, in this case, the list box portion of the combination box. 
ICollectionViewListBox uses this same protocol. 

Note: The ordered collection is enabled for notification. 

collectionReplaced 

Indicates that a new collection is being observed. Effectively, a call to this member 
notifies an ICollectionViewComboBox object that all items in the list box portion of 
the combination box were replaced. The member's default behavior sends the 
ICollectionViewComboBox<Element, Collection>::itemsId notification to all observers 
of this ICollectionViewComboBox object. 

Note: The reporting protocol calls this member after updating all items in the list 
box portion of the combination box. The elementsChanged member handles 
the actual updates to the list box items. 

virtual ICol 1 ectionViewComboBox <Element, Collection^ Supported On: 

collectionReplaced(); PM 


elementAdded 

Indicates that an element was added to the collection at the specified position. 
Effectively, this member notifies ICollectionViewComboBox that an item must be 
added to the list box portion of the combination box. The default behavior generates 
a string for the collection element, using the IStringGenerator object, and inserts the 
generated string into the list box. 

position A 1-based index reference to the added collection element. 
element The new collection element. 
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virtual ICol lectionViewComboBox <Element, Collections 
elementAdded( unsigned long position, 
const Element& element); 


Supported On: 

PM 


elementChanged 

Indicates that a collection element changed state. The collection element's collection 
position is the first parameter. Effectively, this member notifies an 
ICollectionViewComboBox object that the list box item corresponding to the 
collection element needs updating. The default behavior regenerates the string 
representation for this collection element and replaces the corresponding item in the 
list box portion of the combination box. 

position A 1-based index reference to the changed collection element. 
element The collection element that changed. 


virtual ICol lectionViewComboBox <Element, Collections 
elementChanged( unsigned long position, 
const Element& element); 


Supported On: 

PM 


elementDeleted 

Indicates that a collection element was deleted at the specified position. Effectively, 
this member notifies an ICollectionViewComboBox object that the corresponding 
item must be deleted from the list box portion of the combination box. The default 
behavior deletes the list box item. 

position A 1-based index that specifies the collection position of the deleted 
collection element prior to the delete. 


virtual ICol lectionViewComboBox <Element, Collections Supported On: 

elementDeleted( unsigned long position); PM 

elementsChanged 

Indicates that at least one element and possibly all elements in the viewed collection 
have changed. Effectively, this member notifies an ICollectionViewComboBox object 
that all items in the list box portion of the combination box need updating based on 
the current state of the viewed collection. The default behavior deletes all items from 
the list box portion of the combination box and repopulates that list box from the 
collection's contents. 


virtual ICol lectionViewComboBox <Element, Collections 
elementsChanged (); 


Supported On: 

PM 
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Constructors 

You can construct and destruct objects of this class. 

ICollectionViewComboBox 

Q ICol lectionViewComboBox( unsigned long identifier. Supported On: 

IWindow* parent, PM 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 

const IBaseComboBox::Style& style = IBaseComboBox::defaultStyle( ), 
const IStringGenerator < Element >& stringGenerator = 

IStringGenerator < Element > ( )); 

You can construct objects of this class by using the parent window, owner window, 
optional size and location, optional style, and optional string generator parameters. 

id A combination box control ID. 

parent The parent window. 

owner The owner window. 

initial A rectangle for the control. It specifies the initial position and size of the 

object you are constructing. (Optional) 

style The initial style for the control. The default is 

IBaseComboBox::classDefaultStyle (Vol. II). (Optional) 

stringGenerator 

The initial string generator for the collection view. (Optional) 

This creates the specified combination box control and an object for it. 

£ ICollectionViewComboBox( unsigned long identifier, 

IWindow* parent, 

const IStringGenerator < Element >& stringGenerator 
IStringGenerator < Element > ( )); 

You can construct objects of this class by using the parent window and optional 
string generator parameters. 

id A combination box control ID. 

parent The parent window. 

stringGenerator 

The initial string generator for the collection view. (Optional) 


Supported On: 

PM 
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0 ICol 1 ectionViewComboBox( const IWindowHandle& handle. Supported On: 

const IStringGenerator < Element >& stringGenerator = PM 

IStringGenerator < Element > ( )); 

You can construct objects of this class by using the handle of an existing combination 
box and optional string generator parameters. 

handle The window handle of an existing combination box control. 
stringGenerator 

The initial string generator for the collection view. (Optional) 

ICollectionViewComboBox 

virtual Supported On: 

'ICol 1 ectionViewComboBox(); PM 


Selection 

Use these members to retrieve and manipulate the selection state of an 
ICollectionViewComboBox object. These members act on the list box portion of the 
combination box but use the collection as their reference for parameters and return values. The 
parameters and return values are collection positions or collection elements. The selection 
actions include the following: 

• Selecting or deselecting an item 

• Retrieving the selected item 

Note: A collection operates as if it is a 1-based array of items. The collection position is such 
an index. 

Deselects the item in the list box portion of the combination box corresponding to 
the collection element at collectionPosition. 

collectionPosition 

A 1-based index reference to a collection element. 

Note: In collections, the collection position is a 1-based index (the first item is item 

1). 

virtual ICol 1 ectionViewComboBox <Element, Collections Supported On: 

deselect( unsigned long collectionPosition); PM 

. Selects or deselects the item in the list box portion of the combination box 
corresponding to the collection element at collectionPosition. 

collectionPosition 

A 1-based index reference to a collection element. 
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select If you specify true, the item is selected and any previously selected item 
is deselected. If you specify false, the item is deselected. The default is 
true. 

Note: In collections, the collection position is a 1 -based index (the first item is item 

1). 


virtual ICol 1 ectionViewComboBox <Element, Collection^ 
select( unsigned long collectionPosition, 

Boolean select = true); 


Supported On: 

PM 


selectedCollectionPosition 

Returns the collection position (1-based index) corresponding to the selected item in 
the list box portion of the combination box. 

Note: If no item is selected, noSelection is returned. 


virtual unsigned long 

selectedCol1ectionPosition (); 


Supported On: 

PM 


selectedElement 

Returns the collection element corresponding to the selected item in the list box 
portion of the combination box. 

Note: If no item is selected, an exception is thrown. 

virtual Element Supported On: 

selectedElement() const; PM 


Exceptions 

IlnvalidRequest There is no selected list box item. 


String Generator 

Use these members to set and retrieve the string generator associated with an 
ICollectionViewComboBox object. The default string generator uses Element asString to return a 
string. This member assumes that Element natively supports operators or is an Object* object, 
where Object has an asString member function. 

setStringGenerator 

Replaces the string generator associated with an ICollectionViewComboBox object. 

The string generator provides strings for collection elements for use as items in the 
list box portion of the combination box. Typically, a string generator contains a 
IStringGeneratorMemberFn, which is an Element member function. The string 


© IBM Corp. 1992, 1995 


ICollectionViewComboBox 125 




ICollectionViewComboBox 


generator generates strings by calling the contained member function. Thus, use this 
member to replace the Element member function used to produce strings for the 
collection view items. 

stringGenerator 

A string generator. 


virtual IStringGenerator < Element >& 
setStringGenerator( 

const IStringGenerator < Element >& stringGenerator); 


Supported On: 

PM 


stringGenerator 

Retrieves the string generator associated with an ICollectionViewComboBox object. 
The string generator provides strings for collection elements for use in the list box 
part of the combination box. Use this function to assign one IStringGenerator to 
another; this increments the use count of the optionally contained IStringGeneratorFn. 


virtual IStringGenerator < Element >& 
stringGenerator(); 


Supported On: 

PM 


Inherited Public Functions 


IBaseComboBox 

convertToGUIStyle 

isSelected 

setB ackgroundColor 

count 

itemHandle 

setDefaultStyle 

defauItStyle 

itemText 

setForegroundColor 

deselect 

lay out Adj u stment 

setltemHandle 

deselectAll 

locateText 

setltemText 

elementAt 

minimumRows 

setMinimumRows 

enableNotification 

moveS izeTo 

setTop 

hideList 

numberOfSelections 

showList 

isEmpty 

position 

size 

isHorizontalScroll 

select 

top 

isListShowing 

selection 

topHandle 


IEntryField 

alignment 

enable 

isWriteable 

backgroundColor 

enableAutoScroll 

leftlndex 
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IEntryField 

charType 

enable AutoTab 

limit 

clear 

enableCommand 

moveSizeTo 

convertToGUIStyle 

enableDataUpdate 

paste 

copy 

enablelnsertMode 

removeAll 

cursorPosition 

enableMargin 

selectedRange 

cut 

enableNotification 

selectedText 

defaultStyle 

foregroundColor 

selectedT extLength 

disable 

hasChanged 

selectRange 

disableAutoScroll 

hasSelectedText 

setAlignment 

disable AutoTab 

isAutoScroll 

setChangedFlag 

disableCommand 

is AutoTab 

setCharType 

disableDataUpdate 

isCommand 

setCursorPosition 

disablelnsertMode 

isEmpty 

setDefaultStyle 

disableMargin 

isInsertMode 

setLeftlndex 

discard 

isMargin 

setLimit 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Functions 


IBaseComboBox 

calcMinimumSize 

incrementChangeCount 

setLayoutDistorted 

changeCount 

registerCallbacks 

unregisterCallbacks 


IEntryField 

calcMinimumSize 

passEventToOwner 

setLayoutDistorted 

initialize 

registerCallbacks 

setStyle 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 

Notification Members 

These members define the possible notifications that ICollectionViewComboBox provides to its 
observers. The following events can be observed: 

• An item changed in the list box portion of the combination box. 

• All items in the list box portion of the combination box changed. 

itemChangedld 

Notification identifier provided to observers when a combination box item changes 
due to a change in the underlying collection element. 

ICollectionViewCombinationBox<Element, Collection> provides the changed 
collection element in the INotificationEvent::eventData (Vol. I) field of the 
INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

itemChangedld; PM 

-Notification identifier provided to observers when the collection underlying the 
collection view combination box is changed. ICollectionViewComboBox<Element, 
Collection> provides the a pointer to the new collection in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 
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static INotificationld const 
itemsld; 


Supported On: 

PM 


Selection 

Use these members to retrieve and manipulate the selection state of an 
ICollectionViewComboBox object. These members act on the list box portion of the 
combination box but use the collection as their reference for parameters and return values. The 
parameters and return values are collection positions or collection elements. The selection 
actions include the following: 

• Selecting or deselecting an item 

• Retrieving the selected item 

Note: A collection operates as if it is a 1-based array of items. The collection position is such 
an index. 

- Indicates no item is selected in the list box poriotn of the combination box. 
ICollectionViewComboBox::selectedCollectionPosition returns this value. 

static const unsigned long Supported On: 

noSelection; PM 


Inherited Public Data 


IBaseComboBox 

anyData 

enterld 

notFound 

classDefaultStyle 

first 

oemData 

dbcsData 

horizontalScroll 

readOnlyDropDownType 

dropDownType 

mixedData 

sbcsData 


IEntryField 

anyData 

dataUpdatetd 

margin 

autoScroll 

dbcsData 

mixedData 

autoTab 

end 

oemData 

center Align 

insertModeld 

readonly 

characterT y peld 

leftAlign 

rightAlign 

classDefaultStyle 

limit Id 

sbcsData 

command 

lowerCase 

unreadable 
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ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoiorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICollectionViewConstants 


IBase 

ICollectionViewConstants 


_.None. 


_ icollvwi.hpp 


Member 

Page 

Member 

Page 

listDelete 

131 

listlnsert 

132 

listDeleteAll 

132 

listMemoryError 

132 

listEnd 

132 

listNone 

132 

listError 

132 




The ICollectionViewConstants class provides constants for the 
ICollectionViewListBox and ICollectionViewComboBox template implementation. 
Thus, the constants are intended for use by the ICollectionViewListBox and 
ICollectionViewComboBox classes only. So adhere to the following: 

• Do not create objects of this class. 

• Do not use these constants. 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 

Template Implementation 

You do not use these constants. 

_You do not use this constant. 
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static const unsigned long 
1istDelete; 

—You do not use this constant. 


Supported On: 

PM 


static const unsigned long 
1istDeleteAl1; 

.You do not use this constant. 


Supported On: 

PM 


static const unsigned long 
1 i st End; 

You do not use this constant. 


Supported On: 

PM 


static const unsigned long 
1istError; 

_ You do not use this constant. 


Supported On: 

PM 


static const unsigned long 
1istlnsert; 


Supported On: 

PM 


NstMemoryError 

You do not use this constant. 


static const unsigned long 

Supported On: 

1istMemoryError; 

PM 

.You do not use 

this constant. 


static const unsigned long 

Supported On: 

1istNone; 


PM 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 
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ICollectionViewListBox 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

IBaseListBox 

ICollectionViewListBox 


_.None. 


—ilistcvw.hpp 


Member 

Page 

Constructor 

137 

collectionReplaced 

135 

deselect 

138 

elementAdded 

135 

elementChanged 

136 

elementDeleted 

136 

elementsChanged 

136 

enableExtendedSelect 

138 

extendedSelectChangedld 

142 

itemChangedld 

143 

items 

134 


Member 

Page 

itemsld 

143 

noSelection 

143 

select 

139 

selectedCollectionPosition 

139 

selectedElement 

139 

selectedElements 

140 

setltems 

134 

setStringGenerator 

140 

stringGenerator 

141 

“ICollection V iewListB ox 

138 


The ICollectionViewListBox<Element, Collection> template class provides a view of 
an ordered collection, as items in a list box. Template class Element is the type of 
objects in the collection, and template class Collection is the type of collection. The 
sequence of elements is the same between the ordered collection and list box. The 
ICollectionViewListBox interface consists of the following: 

• Population and query members for accessing the collection 

• Collection-reporting protocol for receiving and handling collection updates 

• String generator for translating elements to IStrings 

• Selection members 

• Notification members 

The setltems member populates the list box from collection elements. The items 
member returns the collection being viewed. 
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The collection-reporting protocol refers to the virtual member functions, such as 
elementsChanged, that handle reported changes in the observed collection. 
ICollectionViewListBox objects observe the currently viewed collection (initialized on 
setltems) and report collection updates via calls to the collection-reporting members. 
Then, the collection-reporting members update the list box. 

The string generator object translates collection elements to their IString 
representations. The default string generator assumes that the collection elements 
natively support operators or are Object* objects, where Object has an asString 
member function. The collection-reporting members use this string generation 
mechanism in their processing. 

The selection members query and manipulate the selection state of the list box based 
on collection elements. This includes the following: 

• Selecting or deselecting based on an item's collection position 

• Querying what collection elements correspond to the selected items in the list 
box. 

An ICollectionViewListBox object sends notifications so that observers can monitor, 
and process the following events: 

• The viewed collection is replaced. 

• The extended selection style attribute changes. 

• An item changes in the list box (due to an update of the corresponding collection 
element). 


Public Functions 
Collection 

Use these members to set and retrieve the collection currently being viewed by the 
ICollectionViewListBox object. 

Returns the collection currently being viewed. Typically, items is used by the 
collection-reporting members to retrieve the collection that this control is responsible 
for viewing. 


virtual Collection* Supported On: 

iterns() const; PM 

_ Changes the underlying viewed collection for the list box. Effectively, this 
repopulates the list box with items corresponding to the elements in the new 
collection. This is the only direct way to populate the ICollectionViewListBox object's 
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list box. All other changes to list box items result from changes to the underlying 
collection elements reported via the collection-reporting protocol. 

collection A pointer to a collection. ICollectionViewListBox supports collections 
that are descendents of IPartOrderedCollection. 


virtual ICollectionViewListBox <Element , Collection^ 
setltems( Collection* collection); 


Supported On: 

PM 


Collection-Reporting Protocol 

Use these members to handle reported changes in the underlying ordered collection. As a set, 
they are a protocol through which changes in the collection are reported and subsequently 
processed via updates to the control, in this case, the list box. ICollectionViewComboBox uses 
this same protocol. 

Note: The ordered collection is enabled for notification. 

collectionReplaced 

Indicates that a new collection is being observed. Effectively, a call to this member 
notifies an ICollectionViewListBox object that all items in the list box were replaced. 
The member's default behavior sends the ICollectionViewListBox<Element, 
Collections :itemsld notification to all observers of this ICollectionViewListBox 
object. 

Note: The collection-reporting protocol calls this member after updating all items in 
the list box. The elementsChanged member handles the actual updates to the 
list box items. 

virtual ICol 1 ectionViewListBox <E1 ement , Collection^ Supported On: 

collectionReplaced(); PM 


elementAdded 

Indicates that an element was added to the collection at the specified position. 
Effectively, this member notifies ICollectionViewListBox that an item must be added 
to the list box. The default behavior generates a string for the collection element, 
using the IStringGenerator object, and inserts the generated string into the list box. 

position A 1-based index reference to the added collection element. 
element The new collection element. 
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virtual ICollectionViewListBox <Element , Collections 
elementAdded( unsigned long position, 
const Element& element); 


Supported On: 

PM 


elementChanged 

Indicates that a collection element at the specified position changed its state. 
Effectively, this member notifies an ICollectionViewListBox object that the list box 
item corresponding to the collection element needs updating. The default behavior 
regenerates the string representation for this collection element and replaces the 
corresponding item in the list box. 

position A 1-based index reference to the changed collection element. 
element The collection element that changed. 


virtual ICollectionViewListBox <Element , Collections 
elementChanged( unsigned long position, 
const Element& element); 


Supported On: 

PM 


elementDeleted 

Indicates that a collection element was deleted at the specified position. Effectively, 
this member notifies an ICollectionViewListBox object that the corresponding item 
must be deleted from the list box. The default behavior deletes the list box item. 

position A 1-based index that specifies the collection position of the deleted 
collection element prior to the delete. 


virtual ICol 1 ectionViewListBox <E1 ement, Collections Supported On: 

elementDeleted( unsigned long position); PM 

elementsChanged 

Indicates that at least one element and possibly all elements in the viewed collection 
have changed. Effectively, this member notifies an ICollectionViewListBox object 
that all items in the list box need updating based on the current state of the viewed 
collection. The default behavior deletes all items from the list box and repopulates 
that list box from the collection's contents. 


virtual ICol 1 ectionViewLi stBox <E1 ement, Collections 
elementsChanged (); 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. 
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[] ICol 1 ectionViewLi stBox( 

unsigned long identifier, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const IBaseListBox::Style& style = 

IBaseListBox::defaultStyle ( ) 
const IStringGenerator < Element >& stringGenerator = 
IStringGenerator < Element > ( )); 


Supported On: 

PM 


You can construct objects of this class by using the parent window, owner window, 
optional size and location, optional style, and optional string generator parameters. 


id A list box control ID. 

parent The parent window. 

owner The owner window. 

initial A rectangle for the control. It specifies the initial position and size of the 
object you are constructing. (Optional) 

style The initial style for the control. The default is 

IBaseListBox::classDefaultStyle (Vol. II). (Optional) 


stringGenerator 

The initial string generator for the collection view. (Optional) 


This creates the specified list box control and an object for it. 


S 

You can construct objects of this class by using the parent window and optional 
string generator parameters. 

id A list box control ID. 

parent The parent window. 

stringGenerator 

The initial string generator for the collection view. (Optional) 


ICol 1 ectionViewLi stBox( Supported On: 

unsigned long identifier, PM 

IWindow* parent, 

const IStringGenerator < Element >& stringGenerator = 

IStringGenerator < Element > ( )); 
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g ICollectionViewListBox( Supported On: 

const IWindowHandle& handle, PM 

const IStringGenerator < Element >& stringGenerator = 

IStringGenerator < Element > ( )); 

You can construct objects of this class by using the handle of an existing list box and 
optional string generator parameters. 

handle The window handle of an existing list box control. 
stringGenerator 

The initial string generator for the collection view. (Optional) 


"ICollectionViewListBox 


virtual 

'ICol 1 ectionVi ewLi stBox(); 


Supported On: 

PM 


Selection 

Use these members to retrieve and manipulate the selection state of an ICollectionViewListBox 
object. These members act on the list box but use the collection as their reference for parameters 
and return values. The parameters and return values are collection positions or collection 
elements. The selection actions include the following: 

• Selecting or deselecting an item 

• Retrieving the selected item 

• Retrieving the selected items as a collection 

Note: A collection operates as if it is a 1-based array of items. The collection position is such 
an index. 

Deselects the item in the list box corresponding to the collection element at 
collectionPosition. 

collectionPosition 

A 1-based index reference to a collection element. 

Note: In collections, the collection position is a 1-based index (the first item is item 

1). 

virtual ICol 1 ectionViewListBox <E1 ement. Collections Supported On: 

deselect( unsigned long collectionPosition); PM 

enableExtendedSelect 
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Enables or disables the style IBaseListBox::extendedSelect (Vol. II) for the list box 
and sends the IBaseCollectionListBox<Element, 

Collection>::extendedSelectChangedId notification. 

virtual ICol 1 ectionViewListBox <E1 ement. Collections Supported On: 

enableExtendedSelect( Boolean extended = true); PM 

..Selects or deselects the item in the list box corresponding to the collection element 
at collectionPosition. 

collectionPosition 

A 1-based index reference to a collection element. 
select If you specify true, based on the list box's selection style, the following 
occurs : 

Single selection The specified item is selected and any previously 

selected item is deselected. 

Multiple selection The specified item is selected. 

Extended selection The specified item is selected. 

The default is true. 

Note: In all cases, if you specify false, the item is deselected. 

Note: In collections, the collection position is a 1-based index (the first item is item 

1). 

virtual ICol 1 ectionViewLi stBox <E1 ement. Collections Supported On: 

select( unsigned long collectionPosition, PM 

Boolean select = true); 

selectedCollectionPosition 

Returns the collection position (1-based index) corresponding to the selected item in 
the list box portion of the combination box. For single-selection list boxes, the index 
of the selected item is returned. For multiple-selection or extended-selection list 
boxes, the index of the first selected item is returned. 

Note: If no item is selected, noSelection is returned. 

virtual unsigned long 

selectedCol1ectionPosition (); 

selectedElement 

Returns the collection element corresponding to the selected item in the list box. For 
single-selection list boxes, the element corresponding to the selected item is returned. 


Supported On: 

PM 
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For multiple-selection or extended-selection list boxes, the element corresponding to 
the first selected item is returned. 

Note: If no item is selected, an exception is thrown. 

virtual Element Supported On: 

selectedElement() const; PM 

Exceptions 

IlnvalidRequest There are no list box items selected. 


selectedElements 

Returns a collection of elements corresponding to the selected list box items. It 
deletes all items from the collection parameter before filling it with the elements 
corresponding to the selected list box items. Thus, if no items are selected, an empty 
collection is returned. 

elements A collection for returning elements corresponding to the selected list box 
items. 


virtual ICol 1 ectionViewListESox <E1 ement, Collections 
selectedElements( Collection& elements); 


Supported On: 

PM 


String Generator 

Use these members to set and retrieve the string generator associated with the 
ICollectionViewListBox object. The default string generator uses Element asString to return a 
string. This member assumes that Element natively supports operators or is an Object* object, 
where Object has an asString member function. 

setStringGenerator 

Replaces the string generator associated with an ICollectionViewListBox object. The 
string generator provides strings for collection elements for use as items in the list 
box portion of the combination box. Typically, a string generator contains a 
IStringGeneratorMemberFn, which is an Element member function. The string 
generator generates strings by calling the contained member function. Thus, use this 
member to replace the Element member function used to produce strings for the 
collection view items. 

stringGenerator 

A string generator. 
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virtual IStringGenerator < Element >& Supported On: 

setStringGenerator( PM 

const IStringGenerator < Element >& stringGenerator); 


stringGenerator 

Retrieves the string generator associated with an ICollectionViewListBox object. The 
string generator provides strings for collection elements for use as list box items. 

Note: IStringGenerator supports copying or assigning IStringGenerator objects; it 
handles the proper reference counting of the optionally contained 
IStringGeneratorFn. 


virtual IStringGenerator < Element >& 
stringGenerator(); 


Supported On: 

PM 


Inherited Public Functions 


IBaseListBox 

backgroundColor 

enableN o Adj ustPosition 

minimumRows 

convertToGUIStyle 

enableNotification 

numberOfSelections 

count 

isDrawItem 

select 

defaultStyle 

isEmpty 

selectAll 

deselect 

isExtendedSelect 

selection 

deselectAll 

isHorizontalScroll 

setDefaultStyle 

disableDrawItem 

isMultipleSelect 

setltemHandle 

disableExtendedSelect 

isNoAdjustPosition 

setltemHeight 

disableMultipleSelect 

isSelected 

setltemText 

disableNoAdjustPosition 

itemHandle 

setLay outDi storted 

elementAt 

itemHeight 

setMinimumCharacters 

enableDrawItem 

itemText 

setMinimumRows 

enableExtendedSelect 

locateText 

setTop 

enableMultipleSelect 

minimumCharacters 

show 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 
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INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Functions 


IBaseListBox 

calcMinimumSize 

incrementChangeCount 

registerCallbacks 

changeCount 

passEventT oO wner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 

Notification Members 

These members define the possible notifications that ICollectionViewListBox provides to its 
observers. The following events can be observed: 

• An item changed in the list box. 

• All items in the list box changed. 

• The extended selection style for the list box changed. 


extendedSelectChangedld 

Notification identifier provided to observers when the extended select state of the list 
box changes. 
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static INotificationld const 
extendedSelectChangedld; 


Supported On: 

PM 


itemChangedld 

Notification identifier provided to observers when a list box item changes due to a 
change in the underlying collection element. ICollectionViewListBox<Element, 
Collection> provides the changed collection element in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

itemChangedld; PM 

...Notification identifier provided to observers when the collection underlying the 
collection view list box is changed. ICollectionViewListBox<Element, Collection> 
provides the a pointer to the new collection in the INotificationEvent: :eventData (Vol. 
I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

itemsld; PM 


Selection 

Use these members to retrieve and manipulate the selection state of an ICollectionViewListBox 
object. These members act on the list box but use the collection as their reference for parameters 
and return values. The parameters and return values are collection positions or collection 
elements. The selection actions include the following: 

• Selecting or deselecting an item 

• Retrieving the selected item 

• Retrieving the selected items as a collection 

Note: A collection operates as if it is a 1-based array of items. The collection position is such 
an index. 

- Indicates no list box item is selected. 

ICollectionViewListBox::selectedCollectionPosition returns this value. 

static const unsigned long Supported On: 

noSelection; PM 


Inherited Public Data 
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IBaseListBox 

classDefaultStyle 

extendedSeleet 

muItipleSelect 

drawltem 

first 

noAdjustPosition 

enterld 

horizontalScroll 

notFound 


IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

IContainerColumn 


_.None. 

_icnrcol.hpp 


Member 

Page 

Member 

Page 

Constructor 

147 

horizontalSeparator 

159 

alignBottom 

160 

icon 

161 

alignCentered 

160 

invalidate 

157 

alignLeft 

160 

invisible 

159 

alignRight 

160 

isDate 

152 

alignTop 

161 

isHeadinglconHandle 

152 

align V erticallyCentered 

161 

isHeadingString 

152 

classDefaultDataStyle 

158 

isHeadingWriteable 

152 

classDefaultHeadingStyle 

160 

isIconHandle 

153 

columnlnfo 

157 

isNumber 

153 

container 

157 

isString 

153 

dataAsDate 

147 

isTime 

153 

dataAsIcon 

148 

isVisible 

153 

dataAsNumber 

148 

isWriteable 

153 

dataAsString 

148 

justify Data 

153 

dataAsTime 

148 

justify Heading 

154 

dataAttributes 

157 

number 

159 

date 

158 

readonly 

159 

defaultDataStyle 

148 

readOnlyHeading 

160 

defaultHeadingStyle 

149 

setColumnlnfo 

157 

disableDataUpdate 

149 

setContainer 

157 

disableHeadingUpdate 

149 

setDataAttributes 

157 

displayWidth 

150 

setDataOffset 

154 

enableDataUpdate 

150 

setDefaultDataStyle 

149 

enableHeadingUpdate 

150 

setDefaultHeadingStyle 

149 

handleDrawItem 

158 

setDisplay Width 

154 

hasHorizontalSeparator 

150 

setHeadinglcon 

155 

has V erticalSeparator 

151 

setHeadingText 

155 

headinglcon 

151 

setHelpId 

155 

headingText 

151 

setTitleAttributes 

158 

helpld 

151 

show 

155 

hide 

151 

showSeparators 

156 

hideSeparators 

151 

string 

161 

horizontalDataAlignment 

152 

time 

159 

horizontalHeadingAlignment 

152 

titleAttributes 

158 
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Member 

Page 

Member 

Page 

verticalDataAlignment 

156 

verticalSeparator 

159 

verticalHeadingAlignment 

156 

“IContainerColumn 

147 


Objects of the IContainerColumn class provide the container with the ability to 
display a details view. 

When using the details view, you must create an IContainerColumn object for each 
column in the details view. Use IContainerControl::addColumn to add the column 
objects to the container. 

This class provides functions to add, delete, and hide columns in a container control. 

It also defines the characteristics of the column header (text or icon) and the position 
of the data in the column record. 

The data in the object and the data displayed in the column are connected. For a user 
to have a details view, derive a class from IContainerObject (p. 241) and extend it 
with the additional fields to display in the columns of the container. You must ensure 
the column object has the following information: 

• The exact offset of the data in the object 

• The type of the data in the object 

The column object must have the correct information because it handles the drawing 
of this data. If the column object does not have the correct information, the behavior 
of the column is undefined. 

The default implementation of a container column has the following: 

• A heading containing centered, read-only text 

• A horizontal separator under the heading 

• A vertical separator between columns 

• String data that is non-editable, left-justified, and centered vertically 
Note: You can add an IContainerColumn object to one container only. 

j _J The container widget automatically creates the leftmost column for details view. 

This column contains the icon and text of the corresponding IContainerObject. If you 
attempt to add columns to a container that represent the icon or text for an 
IContainerObject, the columns are ignored. However, if you add a column 
representing the text for an IContainerObject, the automatically created left-most 
column uses the headingText set for that column. 

IContainerControl::ColumnCursor (p. 219) ignores the automatically created left-most 
column. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IContainerColumn 

Q IContainerColumn( unsigned long dataOffset, Supported On: 

const HeadingStyl e& title = defaul tHeadingStyle ( ), PM. Motif 

const DataStyle& data = defaultDataStyle ( )); 

Construct an IContainerColumn object by providing the offset of the object data to be 
displayed in the column and, optionally, the styles to use for the heading and data. 

§ IContainerColumn( DataSource objectDataType, Supported On: 

const HeadingStyl e& title = defaul tHeadi ngStyl e ( ), PM, Motif 

const DataStyle& data = defaultDataStyle ( )); 

Construct an IContainerColumn object by providing a type of data that is part of 
IContainerObject (p. 241) (as opposed to the user portion of the object) and, 
optionally, the styles to use for the heading and data. 

g IContainerColumn( const IContai nerCol umn& column); Supported On: 

PM, Motif 

Construct an IContainerColumn object by copying from an existing container column. 

"IContainerColumn 


virtual 

'IContainerColumn(); 


Supported On: 

PM, Motif 


Data Retrieval 

Use these members to retrieve data that is stored in an object referenced by this class. 

_ Returns the data referenced by this column in the specified object. The data is 
returned as an IDate (Vol. I). If the type of the data is not IContainerColumn:Mate, 
an IlnvalidRequest exception is thrown. You can call IContainerColumn::isDate to 
determine if this function is valid for a column object. 

IDate Supported On: 

dataAsDate( const IContainerObject* object) const; PM, Motif 
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-.Returns the data referenced by this column in the specified object. The data is 
returned as an IPointerHandle (Vol. II). If the type of the data is not 
IContainerColumn: :icon, an IlnvalidRequest exception is thrown. You can call 
IContaincrColumn::isIconHandle to determine if this function is valid for a column 
object. 

I Poi nterHandl e Supported On: 

dataAs!con( const IContainerObject* object) const; PM. Motif 


dataAsNumber 

Returns the data referenced by this column in the specified object. The data is 
returned as an unsigned long integer. All data types can be returned as an unsigned 
long integer. 

unsigned long Supported On: 

dataAsNumber( const IContainerObject* object) const; PM, Motif 

—Returns the data referenced by this column in the specified object. The data is 
returned as an IString. If the type of the data is not IContainerColumn::string, an 
IlnvalidRequest exception is thrown. You can call IContainerColumn::isString to 
determine if this function is valid for a column object. 

IString Supported On: 

dataAsString( const IContainerObject* object) const; PM. Motif 

-.Returns the data referenced by this column in the specified object. The data is 
returned as an ITime (Vol. I). If the type of the data is not IContainerColumn::time 
(p. 159), an IlnvalidRequest (Vol. I) exception is thrown. You can call 
IContainerColumn::isTime to determine if this function is valid for a column object. 

ITime Supported On: 

dataAsTime( const IContainerObject* object) const; PM. Motif 


Data Style 

In addition to the IContainerColumn::Style types, the data in a column can also contain these 
data styles. 


defaultDataStyle 

Returns the default data style. The default data style is classDefaultDataStyle unless 
you change it using setDefaultDataStyle. 
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static Style 
defaul tDataStyle(); 


Supported On: 

PM, Motif 


setDefaultDataStyle 

Sets the default data style for all subsequent column data. 


static void 

setDefaultDataStyle( const DataStyle& dataStyle); 


Supported On: 

PM, Motif 


Heading Style 

In addition to the IContainerColumn::Style types, the heading can also contain these styles. 

defaultHeadingStyle 

Returns the default heading style. The default heading style is 
classDefaultHeadingStyle (p. 160) unless you have changed it using 
setDefaultHeadingStyle (p. 149). 


static Style Supported On: 

defaul tHeadingStyleQ; PM, Motif 

setDefaultHeadingStyle 

Sets the default heading style for all subsequent column headings. 


static void 

setDefaultHeadingStyle( const HeadingStyle& headingStyle); 


Supported On: 

PM, Motif 


Object Information 

Use these members to query and set the accessible attributes of this class. 


disableDataUpdate 

Prevents editing of the column data. 


virtual IContainerColumn& 
disableDataUpdate(); 


Supported On: 

PM, Motif Ignored 


disableHeadingUpdate 

Prevents editing of the heading. 
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virtual IContainerColumn& Supported On: 

di sabl eHeadi ngUpdateQ ; PM, Motif Ignored 

__Returns the displayable width of the column, in pixels. 

If you want the column object's width, use IContainerControl::detailObjectRectangle 
instead of IContainerColumn::displayWidth. This is because a container details view 
cell is like a rectangle inside of another rectangle: 

• The inner rectangle is the data rectangle of the cell and does not contain the 
required column margin. 

This rectangle's width is either: 

- The value set via IContainerColumn::setDisplayWidth 

- The value queried via IContainerColumn::displayWidth 

• The outer rectangle is the complete cell, including the margins that the container 
control requires. 

This is the value returned by IContainerControl::detailsObjectRectangle. 


(PM 


virtual unsigned long Supported On: 

displayWidthO; PM, Motif Ignored 

This function no longer permits you to use private container memory. This only 
affects users of OS/2 2.0 who have not installed the latest Corrective Service Diskette 
(CSD). If you have installed OS/2 2.1 or OS/2 2.0 with the latest CSD, you should 
not be affected. 


enableDataUpdate 

Permits an edit field to be opened in the column data. This is valid only if the style 
is string. 


virtual IContainerColumn& 
enableDataUpdate( Boolean enable = true); 


Supported On: 

PM, Motif Ignored 


enableHeadingUpdate 

Permits an edit field to be opened on the heading. This is valid only if the style is 
string. 


virtual IContainerColumn& Supported On: 

enabl eHeadi ngllpdate ( Boolean enable = true); PM, Motif Ignored 

hasHorizontalSeparator 

If the column heading has a separator drawn under it, true is returned. 
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Boolean Supported On: 

hasHorizontal Separator() const; PM, Motif 

hasVerticalSeparator 

If the column heading has a vertical separator drawn after the column, true is 
returned. 


Supported On: 

PM, Motif 

_lf the style is icon, the icon in the heading is returned. Otherwise an 
IPointerHandle with a value of 0 is returned. 


Boolean 

hasVerticalSeparator() const; 


virtual IPointerHandle Supported On: 

headinglconQ const; PM, Motif Ignored 

_If the style is string, the text in the heading is returned. Otherwise, an empty 
IString is returned. 


virtual IString Supported On: 

headingText() const; PM, Motif 

Retrieves the help panel ID. You set the help panel ID by calling the function 
IContainerColumn:isetHelpId. If you have attached an ICnrHandler to the container, 
the handler will display this help panel when the user requests help while 
direct-editing the column data of the details view. 


unsigned long Supported On: 

helpIdO const; PM, Motif 

.Hides the column by making it invisible. 


virtual IContainerColumn& 
hide(); 


Supported On: 

PM, Motif 


hideSeparators 

Removes either: 

• The vertical separator after a column 

• The horizontal separator under the column heading 

• Both of the preceding separators 

By default, this function removes both. 
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virtual IContainerCol umn& Supported On: 

hi deSeparators ( const DataStyle& separatorStyl es = PM, Motif Ignored 

horizontalSeparator | vertical Separator); 

horizontalDataAlignment 

Returns the current horizontal alignment of the column data in a container details 
view. The returned value is an enumerator provided by HorizontalAlignment (p. 

161). 


Hori zontal A1 i gnment Supported On: 

horizontalDataAlignment() const; PM, Motif Ignored 

horizontalHeadingAlignment 

Returns the current horizontal alignment of the column heading data in a container 
details view. The returned value is an enumerator provided by HorizontalAlignment 

(p. 161). 


Hori zontal A1 i gnment Supported On: 

hori zontal HeadingAli gnment () const; PM, Motif Ignored 

If the data in the column is a date, true is returned. 


Bool ean Supported On: 

1 'sDateO const; PM, Motif 

isHeadinglconHandle 

If the data in the column heading is an icon, true is returned. 


Boolean 

isHeadingIconHandle() const; 


Supported On: 

PM, Motif Ignored 


isHeadingString 

If the data in the column heading is a character string, true is returned. 


Supported On: 

PM, Motif Ignored 

isHeadingWriteable 

If the data in the column heading can be edited, true is returned. 


Boolean 

isHeadingString() const; 
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Boolean 

isHeadingWriteable() const; 

_If the data in the column is an icon, true is returned. 


Supported On: 

PM, Motif Ignored 


Boolean 

isIconHandle() const; 

_If the data in the column is a number, true is returned. 


Supported On: 

PM, Motif 


Boolean Supported On: 

isNumber() const; PM, Motif 

.If the data in the column is a pointer to a character string or an IString (Vol. I), true 
is returned. 


Boolean 

isString() const; 

. If the data in the column is a time, true is returned. 


Supported On: 

PM, Motif 


Boolean 

isTime() const; 

.If the column is visible in the container, true is returned. 


Supported On: 

PM, Motif 


Boolean 

isVisible() const; 

_If the user can edit the data in the column, true is returned. 


Supported On: 

PM, Motif 


Boolean Supported On: 

isWriteableO const; PM, Motif Ignored 

_Sets the justification of the data to a horizontal and vertical alignment. Use the 
enumeration Horizontal Alignment (p. 161) to set the horizontal alignment to left, 
right, or centered. Vertical Alignment (p. 162) sets the vertical alignment to top, 
bottom, or centeredVertically. 


virtual IContainerColumn& 

justifyData( VerticalAlignment = centeredVertically, 
HorizontalAlignment = centered); 


Supported On: 

PM, Motif Ignored 
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justifyHeading 

Sets the justification of the heading to a horizontal and vertical alignment. Use the 
enumeration Horizontal Alignment (p. 161) to set the horizontal alignment to left, 
right, or centered. Vertical Alignment (p. 162) sets the vertical alignment to top, 
bottom, or centered Vertically. 


virtual IContainerColumn& Supported On: 

justifyHeading( PM, Motif Ignored 

VerticalAlignment = centeredVertically, 

HorizontalAlignment = centered); 


setDataOffset 

Identifies where the data is located in a container object for this column. 

The data in the object and the data displayed in the column are connected. For a user 
to have a details view, you must derive a class from IContainerObject (p. 241) and 
extend it with the additional "fields" to display in the columns of the container. You 
must ensure the column object has the following information: 

• The exact offset of the data in the object 

• The type of the data in the object 

The column object must have the correct information because it handles the drawing 
of this data. If the column object does not have the correct information, the behavior 
of the column is undefined. 

virtual IContai nerCol umn& Supported On: 

setDataOffset( unsigned long dataOffset); PM, Motif 


setDisplayWidth 

Returns the displayable width of the column, in pixels, after showing the details view. 

If you want the column object's width, use IContainerControl::detailObjectRectangle 
instead of IContainerColumn::displayWidth. This is because a container details view 
cell is like a rectangle inside of another rectangle: 

• The inner rectangle is the data rectangle of the cell and does not contain the 
required column margin. 

This rectangle’s width is either: 

- The value set via IContainerColumn::setDisplayWidth 

- The value queried via IContainerColumn::displayWidth 

• The outer rectangle is the complete cell, including the margins that the container 
control requires. 
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This is the value returned by IContainerControl::detailObjectRectangle. 


virtual IContainerColumn& 

setDisplayWidth( unsigned long widthlnPixels); 


Supported On: 

PM, Motif Ignored 


setHeadinglcon 

Sets the icon to use for the heading and changes the style to icon. 


| virtual IContainerColumn& 

setHeadinglcon( unsigned long iconld); 


Supported On: 

PM. Motif Ignored 


£ virtual IContainerColumn& 

setHeadinglcon( const IPointerHandle& iconHandle); 


Supported On: 

PM. Motif Ignored 


g virtual IContainerColumn& 

setHeadinglcon( const IResourceId& iconld); 


Supported On: 

PM, Motif Ignored 


setHeadingText 

Sets the text to use for the heading and changes the style to string. 


| virtual IContainerColumn& 

setHeadingText( const IResourceId& textld); 


Supported On: 

PM, Motif 


£ virtual IContai nerCol umn& Supported On: 

setHeadi ngText ( const char* text); PM, Motif 

...Stores a help panel ID. You set the help panel ID by calling the function 
IContainerColumn::setHelp!d. If you have attached an ICnrHandler to the container, 
the handler displays this help panel when the user requests help while direct-editing 
the column data of the details view. 

virtual IContainerColumn& 

setHelpld( unsigned long helpld); 

.Makes the column visible. 


virtual IContainerColumn& 

show( Boolean visible = true); 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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showSeparators 

Adds either: 

• The vertical separator after a column 

• The horizontal separator under the column heading 

• Both of the preceding separators 

By default, this function adds both. 

Note: This function removes any separators previously set. If the column currently 
has a horizontal separator and showSeparators(verticalSeparator) is used to 
add a vertical separator, the horizontal separator will be removed. 


virtual IContainerColumn& Supported On: 

showSeparators ( const DataStyle& separatorStyl es = PM, Motif Ignored 

horizontalSeparator | vertical Separator); 


vertical DataAlig nment 

Returns the current alignment of column data in a container details view. The 
returned value is an enumerator provided by Vertical Alignment (p. 162). 

Verti cal A1 i gnment Supported On: 

verti cal DataAl ignment() const; PM, Motif Ignored 

verticalHeadingAlignment 

Returns the current alignment of column heading data in a container details view. 

The returned value is an enumerator provided by VerticalAlignment (p. 162). 


VerticalAlignment 
vertical HeadingAlignment() const; 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Object Attributes 

These members implement the class. 

- Returns the address of the container's column record. 

_FIELDINFO* 

columnInfo() const; 

-Returns the container in which this column is located. 


IContainerControl* 
container() const; 


dataAttributes 

Returns the current data attributes in the container. 


virtual unsigned long 
dataAttributes() const; 

-If the column is in a container, the column is refreshed. 


IContainerColumn& 
inval idate(); 


setColumnlnfo 

Stores the address of the container's column record. 


IContainerColumn& 

setColumnInfo( _FIELDINFO* fieldinfo); 

— Stores the specified container, which is the container this 


IContainerColumn& 

setContainer( IContainerControl* container); 


setDataAttributes 

Sets the specified attributes into the data. 


virtual IContainerColumn& 

setDataAttributes( unsigned long dataAttributes); 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 

column is located in. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif Ignored 
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setTitleAttributes 

Sets the specified attributes into the title. 


virtual IContainerColumn& 

setTitleAttributes( unsigned long titleAttributes); 


Supported On: 

PM, Motif Ignored 


titleAttributes 

Returns the current title attributes in the container. 


virtual unsigned long 
titleAttributes() const; 


Supported On: 

PM, Motif Ignored 


Public Data 
Data Style 

In addition to the IContainerColumn::Style types, the data in a column can also contain these 
data styles. 

classDefau It DataStyle 

Specifies the original default style for data in a column, which is string, 
alignVerticallyCentered, alignLeft, and readonly. 

static const DataStyle Supported On: 

classDefaultDataStyle; PM, Motif 

Displays the data in date format with National Language Support enabled. The date 
format is a four-byte field divided in the following order: 

• A single byte for the day 

• A single byte for the month 

• Two bytes for the year 

Note: In OS/2, this format is the same as the CD ATE structure. For additional 
information, see Presentation Manager Programming Reference Volume 3. 

static const DataStyle Supported On: 

date; PM, Motif 


handleDrawItem 

When a details item must be drawn, causes an ICnrDrawItemEvent (p. 69) to be 
dispatched to ICnrDrawHandler::drawDetailsItem (p. 66). 
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static const DataStyle Supported On: 

handleDrawItem; PM, Motif 

horizontalSeparator 

Draws a horizontal separator beneath column headings. 


static const DataStyle Supported On: 

horizontalSeparator; PM, Motif 

Hides the data in the column by making it invisible. 


static const DataStyle Supported On: 

invisible; PM, Motif 

_ Specifies the data is an unsigned long number. 


static const DataStyle Supported On: 

number; PM, Motif 

_ Disables editing of the data in the column. 


static const DataStyle Supported On: 

readonly; PM, Motif 

Displays the data in a time format with National Language Support enabled. The 
time format is a four-byte field divided in the following order: 

• A single byte for the hours 

• A single byte for the minutes 

• A single byte for the seconds 

• A final byte, which is reserved 

Note: In OS/2, this format is the same as the CTIME structure. For additional 
information, see Presentation Manager Programming Reference Volume 3. 

static const DataStyle Supported On: 

time; PM, Motif 


verticalSeparator 

Draws a vertical separator after the column. 


static const DataStyle 
verti cal Separator; 


Supported On: 

PM, Motif 
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Heading Style 

In addition to the IContainerColumn::Style types, the heading can also contain these styles. 

classDefaultHeadingStyle 

Specifies the original default style for a heading, which is string, 
alignVerticallyCentered, alignLeft, and readOnlyHeading. 

static const HeadingStyle Supported On: 

ClassDefaultHeadingStyle; PM, Motif 

readOnlyHeading 

Disables editing the data in the heading. 


static const HeadingStyle 
readOnlyHeading; 


Supported On: 

PM, Motif 


Styles 

These style members are both heading styles and data styles. You can specify alignTop, 
alignBottom, and alignVerticallyCentered, and only one of alignLeft, alignRight, and 
alignCentered. 

Aligns the data to the bottom of the cell. 


static const Style 
al ignBottom; 


Supported On: 

PM, Motif 


alignCentered 

Centers the data horizontally in the cell. 


static const Style Supported On: 

alignCentered; PM, Motif 

.Aligns the data to the left of the cell. 


static const Style Supported On: 

alignLeft; PM, Motif 

.Aligns the data to the right of the cell. 


static const Style 
al ignRight; 


Supported On: 

PM, Motif 
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.Aligns the data to the top of the cell. 


static const Style Supported On: 

alignTop; PM, Motif 

alignVerticallyCentered 

Centers the data vertically in the cell. 


static const Style 
al ignVerticallyCentered; 

Specifies the data is an icon. 


Supported On: 

PM, Motif 


static const Style 
icon; 

Specifies the data is a string. 


Supported On: 

PM, Motif 


static const Style 
string; 


Supported On: 

PM, Motif 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Type Definitions 


HorizontalAlignment 

HorizontalAlignment { 
left, 
right, 
centered 
}; 


These enumerators specify the horizontal alignment of text in the column: 

left 

Left-justifies the text in the column. 


right 

Right-justifies the text in the column. 
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centered 

Centers the text horizontally in the column. 


DataSource { 
isI con, 

i slconViewText 

}; 


These enumerators specify whether the column data is the icon or the icon text stored 
in the object: 

islcon 

Uses the icon from the icon view. 

isIconViewText 

Uses the text from the icon view. 


VerticalAlignment 

VerticalAlignment { 
top, 
bottom, 

centeredVertically 

1 ; 


These enumerators specify the vertical alignment of text in the column: 

top 

Aligns the text at the top of the column. 

bottom 

Aligns the text at the bottom of the column. 

centered V ertically 

Centers the text vertically in the column. 


typedef unsigned long HeadingStyle; 

A flag used to represent construction values for the column heading. 


typedef unsigned long Style; 

A flag used to represent construction values for both the column heading and the 
column data. 


typedef unsigned long DataStyle; 

A flag used to represent construction values for the data in a column. 
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IBase 

IVBase 

INotifier 

IWindow 

IControl 

IContainerControl 


_.None. 


__icnrctl.hpp 


Member 

Page 

Member 

Page 

Constructor 

178 

convertToWorkspace 

190 

addColumn 

179 

copyObjectTo 

187 

addld 

213 

currentEditColumn 

183 

addObject 

167 

currentEditMLE 

183 

addObject After 

167 

currentEditObject 

183 

addObjects 

167 

cursoredObject 

197 

addObj ects After 

167 

defaultAttribute 

174 

alignTitleCentered 

210 

defaultStyle 

204 

alignTitleLeft 

210 

delete AllObj ects 

168 

alignTitleRight 

210 

deleteSelectedObjects 

168 

allObjectsDo 

185 

descendentsOf 

198 

areDetailsViewTitlesVisible 

169 

detail sObjectRectangle 

190 

arrangelcon V iew 

175 

detailsTitleRectangle 

179 

attributes 

208 

details View 

210 

autoPosition 

214 

details V iewPortOnW indo w 

195 

baseRecordSize 

208 

details Vie wPortOnWorkspace 

195 

calcMinimumSize 

208 

details ViewSplit 

179 

classDefaultAttribute 

210 

detailsViewTitles 

210 

classDefaultStyle 

214 

detailsViewTitlesId 

213 

closeEdit 

182 

disableCaching 

185 

collapse 

200 

disableDataUpdate 

201 

collapseTree 

205 

disableDrawBackground 

185 

column 

208 

disableDrawItem 

185 

columnAt 

179 

disableDrop 

201 

columnCount 

179 

disableTitleUpdate 

169 

columnUnderPoint 

190 

editColumnTitle 

183 

containerAttributes 

208 

editContainerTitle 

183 

containerFromHandle 

185 

editObject 

183 

containerKey 

208 

enableCaching 

186 

containerList 

209 

enableDataUpdate 

201 

containsObject 

197 

enableDrawB ackground 

186 

convertToGUIStyle 

204 

enableDrawItem 

186 
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Member 

Page 

Member 

Page 

enableDrop 

201 

isTitleVisible 

171 

enableNotification 

189 

isTitleWriteable 

171 

enableTitleUpdate 

169 

isTreelconView 

182 

enterld 

213 

isTreeNameView 

182 

expand 

201 

isTreeTextView 

182 

expandTree 

205 

isTreeView 

182 

extendedSelection 

214 

isVisible 

192 

filter 

184 

isWriteable 

195 

flowed View 

211 

lineSpacing 

171 

handleDrawB ackground 

211 

miniicons 

211 

handleDrawItem 

211 

mixedTargetEmphasis 

211 

hasMixedT argetEmphasis 

169 

movelconTo 

191 

hasNormalT argetEmphasi s 

169 

moveObjectTo 

189 

hasOrderedTargetEmphasis 

170 

multipleSelection 

215 

hideDetailsViewTitles 

170 

name View 

212 

hideObject 

201 

nlsCompare 

204 

hideSourceEmphasis 

201 

noSharedObjects 

215 

hideSplitBar 

179 

numberOfColumnChanges 

187 

hideTitle 

170 

numberOfObj ectChanges 

187 

hideTitleSeparator 

170 

object At 

198 

hideTreeLine 

205 

objectCount 

198 

hwndAllocation 

209 

objectList 

198 

iconRectangle 

191 

objectUnderPoint 

191 

iconSize 

170 

operator == 

178 

icon View 

211 

orderedTargetEmphasis 

212 

immediateDescendentsOf 

198 

parentObject 

198 

initialize 

184 

readonly 

215 

isCachingEnabled 

186 

readOnlyTitle 

212 

isCollapsed 

193 

refresh 

192 

isColumnRight 

180 

refreshAllContainers 

196 

isCursored 

193 

registerCallbacks 

207 

isDetailsView 

181 

remove AllObj ects 

168 

i sDrawB ackgroundEnabled 

186 

removeColumn 

180 

isDrawItemEnabled 

186 

removeColumnAt 

180 

isDropOnAble 

194 

removeld 

213 

isExpanded 

194 

removelnUse 

202 

isExtendedSelection 

170 

removeObject 

168 

isFlowed 

181 

remo veObj ect At 

168 

isFlowedNameView 

181 

removeSelected 

203 

isFlowedTextView 

181 

removeSelectedObjects 

168 

isIconView 

181 

scroll 

199 

isInUse 

194 

scrollDetailsHorizontally 

199 

isMove Valid 

187 

scrollHorizontally 

199 

isMultipleS election 

170 

scrollToObject 

200 

isNameView 

181 

scroll Vertically 

200 

isRefreshOn 

196 

selectld 

213 

isSelected 

194 

sendEvent 

193 

isShowingMinilcons 

182 

setAttributes 

209 

isSingleSelection 

171 

setB ackgroundColor 

193 

isSource 

194 

setContainerAttributes 

209 

isTarget 

194 

setCursor 

203 

isTextView 

182 

setDefaultAttribute 

174 

isTitleSeparatorVisible 

171 

setDefaultStyle 

205 
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Member 

Page 

Member 

Page 

setDeleteColumnsOnClose 

174 

showSourceEmphasis 

203 

setDeleteObjectsOnClose 

175 

showSplitBar 

180 

setDetailsViewSplit 

180 

sho wText View 

177 

setEditColumn 

184 

showTitle 

173 

setEditMLE 

184 

sho wT itleS eparator 

173 

setEditObject 

184 

sho wT reelcon V iew 

177 

setEmphasis 

209 

showTreeLine 

206 

setExtendedSelection 

171 

showTreeNameView 

177 

setlconSize 

172 

sho wT reeT ext V iew 

177 

setlnUse 

203 

singleSelection 

215 

setLineSpacing 

172 

sort 

204 

setMixedT argetEmphasis 

172 

sortBylconText 

204 

setMultipleSelection 

172 

splitBarOffset 

180 

setN ormalT argetEmphasis 

172 

textRectangle 

191 

setOrderedT argetEmphasis 

172 

text View 

212 

setRefreshOff 

197 

title 

174 

setRefreshOn 

197 

titleld 

214 

setSelected 

203 

titleRectangle 

174 

setSingleSelection 

173 

titleSeparator 

212 

setTitle 

173 

titleVisibleld 

214 

setTitleAlignment 

173 

topHandle 

207 

setTreeExpandlconSize 

205 

tree View 

212 

setTreeltemlcons 

205 

unregisterCallbacks 

208 

setT ree V ie wlndent 

206 

verifyPointers 

215 

showDetailsView 

176 

vie wPortOn W indo w 

195 

showDetailsViewTitles 

173 

vie wPortOn W orkspace 

195 

showFlowedName V iew 

176 

visibleTitle 

212 

showFlowedTextView 

176 

visibleTreeLine 

212 

showIconView 

176 

willDeleteColumnsOnClose 

175 

showMinilcons 

176 

willDeleteObjectsOnClose 

175 

sho wN ameV iew 

177 

'IContainerControl 

178 

showObject 

203 




Objects of the IContainerControl class display a container of objects in any of the 
following supported views: 

• Icon 

• Name 

• Tree 

• Details 

• Text 

Like other controls in the library, you can construct this control in one of the 
following ways: 

• On a window 

• Loaded in a dialog template 

• As a pre-existing control 
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IPM A container will not paint over sibling windows that lie over it. For this reason, a 
container can be hidden by a sibling combination box, group box, or outline box 
control, even if the control does not paint the portion of its window that overlaps the 
container (for example, the interior of a group box). You can cause the container to 
paint correctly by placing it on top of all overlapping sibling windows, either by 
changing the order that you create it relative to its sibling windows, or by using 
function IWindow::positionOnSiblings (Vol. II) or IWindow::positionBehindSibling 
(Vol. II). 

j_ j In AIX, due to the limited capabilities of the container widget under Motif 1.2, the 

User Interface Class Library does not support the following: 

• Drag and drop support via the IDM* classes. 

• Direct editing. 

• Vertical split bar in a details view. 

• Container titles. The library does support details view column titles. 

• Setting refresh on and off. 

• Any emphasis except selection emphasis 

• Draw item, for example, owner draw. 

• Window and workspace coordinates. There is no support for placing 
IContainerObjects at explicit x,y locations. 

• Scrolling functions, for example: 

- scroll 

- scrollDetailsHorizontally 

- scrollHorizontally 

- scrollVertically 

- scrollToObject 

• The IContainerControl constructors that create an object from an existing 
container control or a dialog template. 

• The ICnrHandler overridden member functions that the library does not call: 

- cursoredChanged 

- deltaReached 

- inuseChanged 

- windowScrolled 


Public Functions 

Adding and Removing Objects 

Use these members are used to add and remove objects. 
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. Adds an object to the container. In the tree view, the parent defines the object's 
location. When you specify parentObject, this function adds the object as its last 
immediate descendent. Otherwise, the container adds the object as the last object in 
the root level. 


virtual IContainerControl& 
addObject( const IContainerObject* newObject, 
IContainerObject* parentObject = 0); 


Supported On: 

PM, Motif 


addObjectAfter 

Adds a new object by placing it after a specified object. 

You can add a container object as the first object in the container by specifying 0 for 
afterObject. This places the object at either of the following locations: 

• The beginning of the container 

• If you specify parentObject, the beginning of the subtree specified by this 
parameter 

• After a specified object in the same level of the tree 

If afterObject is nonzero, the container ignores parentObject. The level, in this case, 
is determined by afterObject. 


virtual IContai nerControl & Supported On: 

addObjectAfter( const IContainerObject* newObject, PM, Motif 

const IContainerObject* afterObject, 

IContainerObject* parentObject = 0); 

_Adds multiple objects to the container. In tree view, the parent defines the location 
of the objects. 


virtual IContainerControl& 
addObjects( ICnrAl1ocator& allocator, 

IContainerObject* parentObject = 0); 


Supported On: 

PM, Motif 


addObjectsAfter 

Adds multiple objects to be placed after a given object. If you specify 0 for the 
afterObject argument, the objects will be added as the first objects in the container. 

virtual IContai nerControl & Supported On: 

addObjectsAfter( ICnrAl1ocator& al1ocator, PM, Motif 

const IContainerObject* afterObject, 

IContainerObject* parentObject = 0); 
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delete AllObjects 

Deletes all objects in this container. If an object exists in other containers, it is 
removed from them as well before being deleted. 


virtual IContainerControl& 
deleteA110bjects(); 


Supported On: 

PM. Motif 


deleteSelectedObjects 

Deletes the selected objects in this container. If an object exists in other containers, it 
is removed from them as well before being deleted. 


virtual IContainerControl& Supported On: 

deleteSelectedObjects(); PM, Motif 

removeAllObjects 

Removes all objects from the container. 


virtual IContainerControl& 
removeA110bjects(); 


Supported On: 

PM. Motif 


removeObject 

Removes the specified object from this container or, optionally, all containers. 


virtual IContainerControl& 
removeObject( IContainerObject* object. 

Boolean allContainers = false); 


Supported On: 

PM. Motif 


removeObjectAt 

Removes the object at the specified cursor's position. 


| virtual IContainerControl& 

removeObjectAt( IContainerControl::ObjectCursor& cursor); 


Supported On: 

PM. Motif 


g virtual IContainerControl & 

removeObjectAt( IContainerControl::TextCursor& cursor); 


Supported On: 

PM. Motif 


removeSelectedObjects 

Removes all selected objects from the container. 
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virtual IContainerControl& 
removeSelectedObjects (); 


Supported On: 

PM, Motif 


Appearance 

Use these members to query and set the accessible attributes of this class. 


areDetailsViewTitlesVisible 

Queries whether the column titles are currently displayed for details view. 


Boolean Supported On: 

areDetailsViewTitlesVisible() const; PM, Motif Ignored 

disableTitleUpdate 

Disables the container title from being edited. 

virtual IContainerControl& 
di sabl eTi tl ellpdate(); 

enableTitlellpdate 

Allows the container title to be edited. 

virtual IContainerControl& 
enableTitleUpdate( Boolean enable = true); 

hasMixedTargetEmphasis 

Queries if the mixed target emphasis mode is set for drag operations over this 
container. 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Boolean Supported On: 

hasMixedTargetEmphasis() const; PM, Motif Ignored 

hasNormalTargetEmphasis 

Queries if the regular target emphasis mode is set for drag operations over this 
container. 


Boolean 

hasNormalTargetEmphasis() const; 


Supported On: 

PM, Motif Ignored 
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hasOrderedTargetEmphasis 

Queries if the ordered target emphasis mode is set for drag operations over this 
container. 


Bool ean Supported On: 

hasOrderedTargetEmphasis() const; PM, Motif Ignored 

hideDetailsViewTitles 

Removes column headings from details view. 

virtual IContainerControl& 
hideDetailsViewTitles(); 

Removes the container title from the container. 


virtual IContainerControl& 
hideTitle(); 

hideTitleSeparator 

Removes the title separator from the container window. 

virtual IContainerControl& 
hideTitleSeparator(); 

Returns the icon or bit-map size of all objects. 

ISize 

iconSize() const; 

isExtendedSelection 

Queries whether the container is in extended selection mode. Extended selection is 
an enhanced version of single selection that lets the user select discontiguous sets of 
container items. 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif 


Bool ean Supported On: 

isExtendedSelection() const; PM, Motif 

isMultipleSelection 

Queries whether the container is in multiple selection mode. Multiple selection is a 
mode that allows the user unrestricted selection of objects. 
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Boolean Supported On: 

isMultipleSelectionQ const; PM, Motif 

isSingleSelection 

Queries whether the container is in the single selection mode. In this mode, the user 
(or your code) can only select a single object at a time. Selecting a new object 
removes the selection from a prior object. In a single-selection container one object 
is always selected. If you remove an object with selection emphasis, the container 
selects another object. 

Boolean 

isSingleSelection() const; 

isTitleSeparatorVisible 

Queries whether the title separator is currently displayed. 

Boolean Supported On: 

isTitleSeparatorVisible() const; PM, Motif Ignored 

-.Queries whether the container title is currently displayed. 


Supported On: 

PM, Motif 


Boolean 

isTitleVisible() const; 


Supported On: 

PM, Motif Ignored 


isTitleWriteable 

Returns true if the data in the title can be edited. 

Boolean Supported On: 

isTitleWriteableO const; PM, Motif Ignored 

..Returns the space between lines, in pixels. This is the amount you can add to the 
minimum distance required by the container control for emphasis painting. You 
cannot reduce the minimum distance required by the presentation system. 

1 ong Supported On: 

lineSpacing() const; PM, Motif Ignored 

setExtendedSelection 

Sets the selection mode to extended selection. Extended selection is an enhanced 
version of single selection that lets the user select discontiguous sets of container 
items. 
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virtual IContainerControl& 
setExtendedSelection(); 

_.Sets the icon or bit-map size for all objects. 


Supported On: 

PM. Motif 


virtual IContainerControl& 
setIconSize( const ISize& iconSize); 


Supported On: 

PM, Motif Ignored 


setLineSpacing 

Sets the vertical distance between records. This is the amount you can add to the 
minimum distance required by the container control for emphasis painting. You 
cannot reduce the minimum distance required by the presentation system. 


virtual IContai nerControl & Supported On: 

setLineSpacing( long lineSpacing); PM, Motif Ignored 

setMixedTargetEmphasis 

Sets the drag mode to mixed-target emphasis. 

virtual IContainerControl& 
setMixedTargetEmphasis(); 

setMultipleSelection 

Sets the selection mode to multiple selection. Multiple selection is a mode that gives 

the user unrestricted selection of objects. 

virtual IContainerControl& 
setMultipieSelection(); 

setNormalTargetEmphasis 

Sets the drag mode to normal-target emphasis. 

virtual IContainerControl& 
setNormalTargetEmphasis(); 

setOrderedTargetEmphasis 

Sets the drag mode to ordered-target emphasis. 

virtual IContai nerControl & Supported On: 

setOrderedTargetEmphasis(); PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM. Motif 


Supported On: 

PM, Motif Ignored 
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setSingleSelection 

Sets the selection mode to single selection. In this mode, the user (or your code) can 
only select a single object at a time. Selecting a new object removes the selection 
from a prior object. In a single-selection container one object is always selected. If 
you remove an object with selection emphasis, the container selects another object. 


virtual IContainerControl& 
setSingleSelection(); 

.Sets the title for the container that is displayed in all views. 


Supported On: 

PM, Motif 


| virtual IContainerControl& 

setTitle( const IResourceId& resourceld); 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 

setTitleAlignment 

Sets the alignment attributes for the title. The default centers the title. 


g virtual IContainerControl& 

setTitle( const char* title); 


virtual IContainerControl & 
setTitleAlignment( 

TitleAlignment alignment = centered); 


Supported On: 

PM, Motif Ignored 


showDetailsViewTitles 

Displays column headings in details view. Although you set the column titles (that 
is, headings) for the individual column objects, you must use this function to tell the 
container control to display the column titles for the details view. 


virtual IContai nerControl & Supported On: 

showDetailsViewTitles( Boolean show = true); PM, Motif 

_ Shows the container title. 


virtual IContai nerControl & Supported On: 

showTitle( Boolean show = true); PM, Motif Ignored 

showTitleSeparator 

Displays a horizontal separator between the title and the work area. 


virtual IContainerControl& 

showTitleSeparator( Boolean show = true); 


Supported On: 

PM, Motif Ignored 
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Returns the title of the container. 


virtual IString 
title() const; 


Supported On: 

PM, Motif Ignored 


titleRectangle 

Returns the rectangle that contains the container's title. 

IRectangle Supported On: 

titleRectangleO const; PM, Motif Ignored 

Attributes 

These attribute members provide valid container styles for IContainerControl::setDefaultAttribute 
and for the constructor of the IContainerControl (p. 163) class. 

defaultAttribute 

Returns the default attribute. The default attribute is 

IContainerControl: xlassDefaultAttribute (p. 210) unless you have changed it using 
setDefaultAttribute (p. 174). 


static Attribute Supported On: 

defaultAttribute(); PM, Motif 

setDefaultAttribute 

Sets the default attribute for all subsequent containers. 

attribute Use the attributes provided by IContainerControl::Attribute (p. 218) to 
specify the default attribute. 


static void 

setDefaultAttribute( const Attribute& attribute); 


Supported On: 

PM. Motif 


Automatic Deletion Behavior 

These members describe behavior that occurs automatically when a container is deleted. 


setDeleteColumnsOnClose 

Deletes all columns in the container when the container is deleted. Set only columns 
that are allocated by using operator new for automatic deletion. Because columns can 
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be in multiple containers, the container's default behavior only removes columns but 
does not delete them when the container is deleted. 


virtual IContainerControl& 

setDeleteColumnsOnClose( Boolean destroy = true); 


Supported On: 

PM, Motif 


setDeleteObjectsOnClose 

Deletes all objects in the container when the container is deleted. Because objects 
can be in multiple containers, the container's default behavior only removes objects 
but does not delete them when the container is deleted. 


virtual IContai nerControl & Supported On: 

setDeleteObjectsOnClose( Boolean destroy = true); PM, Motif 

willDeleteColumnsOnClose 

If the columns will be deleted when the container is deleted, true is returned. 


Boolean Supported On: 

will DeleteColumnsOnClose() const; PM, Motif 

willDeleteObjectsOnClose 

If container objects will be deleted when the container is deleted, true is returned. 


Boolean 

will DeleteObjectsOnClose() const; 


Supported On: 

PM, Motif 


Changing Views 

Use these members to change the view. 

arrangelconView 

Arranges the icon view. The icons are arranged in horizontal rows from left to right. 

virtual IContai nerControl & Supported On: 

arrangelconViewQ; PM, Motif 

IPM CM_ARRANGE provides additional information on arrangement in the Presentation 
Manager Programming Reference Volume 3. 
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showDetailsView 

Sets the current view to details view. This member function displays the container 
objects as multiple columns of data with one row for each object. Optionally, you 
can divide the output into two regions using a single vertical split bar. 

virtual IContainerControl & Supported On: 

showDetailsView(); PM. Motif 

showFlowedNameView 

Sets the current view to the flowed name view. 


virtual IContainerControl& Supported On: 

showFlowedNameView(); PM. Motif 

showFlowedTextView 

Sets the current view to the flowed text view. 


virtual IContainerControl& 
showFlowedTextView(); 


Supported On: 

PM. Motif 


showIconView 

Sets the current view to the icon view. If you have called arrangelconView or have 
specified the autoPosition style, this member function displays the container objects as 
icons with the icon text below the icon. If you have more objects than will fit in a 
row, the objects flow into a second row. If there are more rows of objects than will 
fit in your container's window, the user can vertically scroll the container to see the 
rest of the objects. 

virtual IContai nerControl & Supported On: 

showIconViewQ; PM. Motif 

j ~~ In Motif, icon view always uses the style autoPosition. You cannot reposition the 

icons using the mouse. Functions that programmatically relocate icons, such as 
movelconTo, are not supported. 


showMinilcons 

Shows mini icons in any non-text view. For best results provide a 16X16 and a 
20X20 1 bit/pixel version of the image in the .ico file loaded for the 
IContainerObject. When showMinilcons is called, the smaller icons will be 
displayed, otherwise the regular sized icon will be resized accordingly. 
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virtual IContainerControl& 

showMiniIcons( Boolean mini = true); 


Supported On: 

PM, Motif Ignored 


showNameView 

Sets the current view to the non-flowed name view. If there are more objects than 
will fit in the container, the user can vertically scroll the container to see the rest of 
the objects. 


virtual IContainerControl& 
showNameView(); 


Supported On: 

PM, Motif 


showTextView 

Sets the current view to the non-flowed text view. 


virtual IContai nerControl & Supported On: 

showTextView(); PM, Motif 

showT reelcon View 

Displays the objects as icons in a tree to represent their relationship to one another. 


virtual IContai nerControl & Supported On: 

showTreeIconView(); PM, Motif 

showT reeNameView 

Sets the current view to the tree name view. 


virtual IContai nerControl & Supported On: 

showTreeNameView(); PM, Motif 

showTreeTextView 

Displays the objects in a tree to represent their relationship to one another. Unlike 
showTreelconView, this function only displays the object's text and not the object's 
icon. 


virtual IContainerControl& 
showTreeTextView(); 


Supported On: 

PM, Motif 


Comparison 

These operators compare two IContainerControls. 
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_If two containers are the same (that is, their storage location is identical), true is 
returned. 


Boolean 

operator ==( const IContainerControl& container); 


Supported On: 

PM, Motif 


Constructors 

You can construct and destruct objects of this class. 


Note: The AIX version does not support constructing objects from a loaded dialog template or 
from an existing container control's window handle. 


IContainerControl 


[j IContainerControl ( unsigned long id, Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IRectangle& location = IRectangle ( ), 

const Style& style = defaultStyle ( ), 

const Attribute& attribute = defaultAttribute ( )); 

Create an IContainerControl on a window by specifying the parent and owner. 

2 IContainerControl ( unsigned long id, Supported On: 

IWindow* parentDi al og); PM 

Create an IContainerControl from a container control on a loaded dialog template. 

2 IContai nerControl ( const IWi ndowHandl e& handle); Supported On: 

PM 


Create an IContainerControl from an existing container control's window handle 

IContainerControl 


virtual 

"IContainerControl(); 


Supported On: 

PM. Motif 


Details View Functions 

Use these members in the details view. 
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—Adds a column to the container. If you specify afterColumn, the container adds the 
column after this column. Otherwise, the container adds the column as the last 
column. 


virtual IContainerControl& 
addColumn( const IContainerColumn* column, 

const IContainerColumn* afterColumn = 0); 

. Retrieves the column at the specified 0-based index or cursor. 


Supported On: 

PM, Motif 


| IContainerColumn* 

columnAt( const ColumnCursor& cursor) const; 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 

columnCount 

Returns the number of columns in the container. 


IContainerColumn* 

columnAt( unsigned long index) const; 


unsigned long 
columnCount() const; 


Supported On: 

PM, Motif 


detailsTitleRectangle 

Returns the details view, column-title rectangle in container window coordinates. 
This rectangle represents all currently visible column titles in the details view 
window, not just one column. The container must be in details view when this 
function is called. 


IRectangle 

detai1sTitleRectangle( 

Boolean rightSide = false) const; 


Supported On: 

PM, Motif Ignored 


details ViewSplit 

Returns the last column before the split bar. 


IContai nerCol umn* Supported On: 

detai lsViewSplitO const; PM, Motif Ignored 

—Removes the split bar from the details view work area. 


virtual IContainerControl& 
hideSplitBar(); 


Supported On: 

PM, Motif Ignored 
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isColumnRight 

If the specified column is to the right of the split bar, true is returned. 

Bool ean Supported On: 

isColumnRight( const IContainerColumn* column) const; PM. Motif Ignored 

removeColumn 

Removes the specified column from the container. 

virtual IContainerControl& 
removeColumn( const IContainerColumn* column); 

removeColumnAt 

Removes the column at a specified cursor position. 

virtual IContainerControl & Supported On: 

removeCol umnAt ( IContainerControl: :ColumnCursor& cursor); PM. Motif 

setDetailsViewSplit 

Splits the details view. You determine where the split occurs by specifying the last 
column to view in the left window. If a split bar already exists, it is moved to the 
new location. The lastColumnBeforeSplit parameter is the last column that will ever 
be scrolled in the left frame. The pixelsFromLeft parameter is the location of the split 
bar in pixels. 

virtual IContainerControl& 
setDetai1sViewSplit ( 

const IContainerColumn* lastColumnBeforeSplit, 
unsigned long pixelsFromLeft = 50); 

_Adds the split bar to the details view work area. 

virtual IContainerControl& 
showSplitBar( Boolean showSplitBar = true); 

splitBarOffset 

Returns the offset of the split bar, in pixels, from the left side of the container 
window. 

unsigned long Supported On: 

splitBarOffsetO const; PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif 
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Determining the View 

Use these members to query the view. 

-.Queries whether the container is currently in the details view. 

Boolean Supported On: 

isDetailsView() const; PM, Motif 

-Queries whether the current container view is flowed. This function applies to the 
name and text views only. 


Boolean Supported On: 

isFlowed() const; PM, Motif 

isFlowedNameView 

Returns true if the container is currently in flowed name view. 


Boolean Supported On: 

isFlowedNameView() const; PM, Motif 

isFlowedTextView 

Returns true if the container is currently in flowed text view. 


Boolean Supported On: 

isFlowedTextView() const; PM, Motif 

—Queries whether the container is currently in an icon view. If iconOnly is false, true 
is returned for both icon view and tree-icon view. If iconOnly is true, true is returned 
only for icon view. 


Boolean Supported On: 

isIconView( Boolean iconOnly = false) const; PM, Motif 

—Queries whether the container is currently in a name view. If nameOnly is false, 
true is returned for both name view and tree-name view. If nameOnly is true, true is 
returned for only name view. 


Boolean 

isNameView( Boolean nameOnly = false) const; 


Supported On: 

PM, Motif 
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isShowingMinilcons 

Queries whether the container mode is set for displaying mini icons. 

Bool ean Supported On: 

isShowingMini Icons () const; PM, Motif Ignored 

-.Queries whether the container is currently in a text view. If textOnly is false, true is 
returned for both text view and tree-text view. If textOnly is true, true is returned for 
only text view. 


Boolean 

isTextView( Boolean textOnly = false) const; 


Supported On: 

PM. Motif 


isTreelconView 

Returns true only if the container is in tree-icon view. 


Boolean 

isTreeIconView() const; 


Supported On: 

PM. Motif 


isTreeNameView 

Returns true only if the container is currently in tree-name view. 


Boolean 

isTreeNameView() const; 


Supported On: 

PM. Motif 


isTreeTextView 

Returns true only if the container is currently in tree-text view. 


Boolean Supported On: 

isTreeTextView() const; PM. Motif 

—Queries whether the container is currently in a tree view. This includes the 
tree-icon, the tree-text, and the tree-name views. 


Boolean 

isTreeView() const; 


Supported On: 

PM. Motif 


Direct Editing 

Use these members in direct editing in the container. 
-Closes an open edit field. 
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virtual IContainerControl& Supported On: 

closeEditO ; PM, Motif Ignored 

currentEditColumn 

Retrieves the column being edited. If a column is not being edited, 0 is returned. 


IContainerColumn* 
currentEditColumn() const; 


Supported On: 

PM, Motif Ignored 


currentEditMLE 

Retrieves the multiple-line edit (MLE) field being used for editing. If an edit 
operation is not in effect, 0 is returned. 


I Mu 1 ti Li neEdi t* Supported On: 

currentEditMLE() const; PM, Motif Ignored 

currentEditObject 

Retrieves the object being edited. If an object is not being edited, 0 is returned. 


IContainerObject* 
currentEditObject() const; 


Supported On: 

PM, Motif Ignored 


editColumnTitle 

Opens an edit field on a specified column's heading. 


virtual IContai nerControl & Supported On: 

editColumnTitle( IContai nerCol umn* col umn); PM, Motif Ignored 

editContainerTitle 

Opens an edit field on the container title. 


virtual IContainerControl& 
editContainerTitle(); 

-.Opens an edit field on a specified object. 


Supported On: 

PM, Motif Ignored 


virtual IContainerControl& 
editObject( IContainerObject* object, 

IContainerColumn* column = 0); 


Supported On: 

PM, Motif Ignored 
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setEditColumn 

Stores the specified column where editing occurs. 


virtual IContainerControl& Supported On: 

setEditColumn( IContai nerCol umn* col umn); PM, Motif Ignored 

-.Stores the specified multiple-line edit (MLE) field being used for editing. 


virtual IContainerControl& 
setEdi tMLE ( IMul ti LineEdi t* editField); 


Supported On: 

PM, Motif Ignored 


setEditObject 

Stores the specified object where editing occurs. 


virtual IContainerControl& 
setEditObject( IContainerObject* object); 


Supported On: 

PM, Motif Ignored 


Filtering Objects 

Use these members to filter the container. 

Filters the container by calling the specified IContainerControl::FilterFn::isMemberOf 
(p. 226) function for each object in the container. If you do not specify a FilterFn, 
objects currently hidden or filtered from the container are restored to the container. 


| virtual IContainerControl& 

fi1 ter( const IContainerControl::Fi1terFn& fi1terObject); 


Supported On: 

PM. Motif 


Q virtual IContainerControl& 
fi 1 ter(); 


Supported On: 

PM. Motif 


Initialization 

Use these members to initialize the container. 

.. Sets up the container environment. If the first container component you create is an 
IContainerControl, the library calls this function automatically. 


static void 
initial ize(); 


Supported On: 

PM. Motif 
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Iterating Objects 

Use these members to apply behavior to the objects in the container. 

„Calls IContainerControl::Iterator::applyTo (p. 228) on the specified iterator for all 
objects in the container. If you specify true for includeDescendents , the tree view 
descendent objects are called as well. The iteration stops when: 

• IContainerControl::Iterator::applyTo returns true 

• All the objects in the container have been processed 


virtual IContainerControl& Supported On: 

al 10bjectsDo( IContai nerControl:: Iterator& iteratorObject, PM. Motif 

Boolean includeDescendents = false); 


Miscellaneous 

These members provide miscellaneous IContainerControl operations. 


containerFromHandle 

Retrieves a container from the list using the specified handle. 


static IContainerControl* 
containerFromHandle( const IWindowHandle& handle); 


Supported On: 

PM, Motif 


disableCaching 

Stops the dispatch of ICnrQueryDeltaEvents (p. 109) to an ICnrHandler (p. 95). 


virtual IContai nerControl & Supported On: 

disableCaching(); PM. Motif Ignored 

disableDrawBackground 

Stops the dispatch of ICnrDrawBackgroundEvent to an ICnrDrawHandler. 


virtual IContainerControl& 
disableDrawBackground(); 


Supported On: 

PM, Motif Ignored 


disableDrawItem 

Stops the dispatch of ICnrDrawItemEvent to an ICnrDrawHandler. 


virtual IContainerControl& 
disableDrawItem(); 


Supported On: 

PM, Motif Ignored 
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enableCaching 

If an ICnrHandler (p. 95) has been created and added to the container, this function 
causes the dispatch of an ICnrQueryDeltaEvent (p. 109) to the handler when the 
container scrolls past the pre-defmed delta value. 


virtual IContainerControl & Supported On: 

enableCaching( unsigned long deltaValue = 30); PM, Motif Ignored 

enableDrawBackground 

Miscellaneous IContainerControl functions. 


virtual IContainerControl& 
enableDrawBackground( Boolean enable = true); 


Supported On: 

PM, Motif Ignored 


enableDrawItem 

If an ICnrDrawHandler has been created and added to the container, this function 
causes the container to dispatch the ICnrDrawBackltemEvent to its handlers. 
Typically, you process this event by deriving a handler from ICnrDrawHandler and 
overriding the functions of the handler such as drawText and drawlcon. 


Supported On: 

PM, Motif Ignored 

isCachingEnabled 

Queries whether a delta value is set and caching is enabled. 


virtual IContainerControl& 
enableDraw!tem( Boolean enable = true); 


Supported On: 

PM, Motif Ignored 

isDrawBackgroundEnabled 

Queries whether owner draw of the container background is enabled. 


Boolean 

isCachingEnabled() const; 


Supported On: 

PM, Motif Ignored 

isDrawItemEnabled 

Queries whether owner draw of container objects is enabled. 


Boolean 

isDrawBackgroundEnabled () const; 


Boolean 

isDrawItemEnabledO const; 


Supported On: 

PM, Motif Ignored 
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numberOfColumnChanges 

Retrieves the container's count of column additions and removals. 

IContainerControl::ColumnCursor objects use this function to validate their location in 
the container. 

unsigned long Supported On: 

numberOfColumnChanges() const; PM, Motif 

numberOfObjectChanges 

Retrieves the container's count of object additions and removals. 

IContainerControl::ObjectCursor and IContainerControl::TextCursor objects use this 
function to validate their location in the container. 


unsigned long 

numberOfObjectChanges() const; 


Supported On: 

PM, Motif 


Moving and Copying Subtrees 

Use these members to move and copy objects and their descendents. 


copyObjectTo 

Copies an object and its descendents to a new location in the tree view. The object 
must override IContainerObject::objectCopy (p. 245). This function returns a copy of 
the object. 

virtual IContainerObject* Supported On: 

copyObjectTo( IContai nerObject* copyObject, PM, Motif 

IContainerObject* parentObject = 0, 

IContainerControl* newContainer = 0, 

IContainerObject* afterObject = 0, 

const IPoint& iconViewLocation = IPoint ( 0 , 

0 )); 

IPM This function is called during drag and drop. It must be overridden for an object to 
support drag and drop. If you specify 0 for afterObject , the copied object is added as 
the first object in the tree view. 

... Determines whether an object and its descendents can be moved to a new location. 
This function checks the validity of a move to be performed by 
IContainerControl::moveObjectTo (p. 189). 

The parameters are the following: 
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moveObject 

The object and all of its descendents (if any) you want to move. 
newParentObject 

The new parent for moveObject. The default is moveObject becomes a 
root-level object (that is, there is no parent). 

newContainer 

The container that is the target of the move operation. The default is the 
container you are calling this function upon (that is, the source container). 


afterObject 

The object in the target container after which you want to place 
moveObject. If newParentObject is 0 and afterObject is 0, moveObject is 
the first object in the container. If newParentObject is not 0 and 
afterObject is 0, moveObject is the first child of newParentObject. 

In the following list, the source container is the container you are calling this function 
upon. If you specify 0 for the target container, it is the same container as the souce. 
Otherwise, it is another container. 

This function returns false for any of the following reasons: 

• moveObject = 0. 

• The source container does not contain moveObject. 

• The target container does not contain a valid afterObject (that is, nonzero). 

• The target container does not contain a valid newParentObject (that is, nonzero). 

• moveObject and afterObject are the same object. 

• You specify both afterObject and newParentObject (that is, they are both 
nonzero), and newParentObject is not the parent of afterObject in the target 
container. 

• The source and target containers are the same and you specified moveObject to 
become a child of one of its descendents. You cannot move a subtree to become 
a child of one of the subtree's members. 

• The source and target containers are different and moveObject or any of its 
descendents already exist in the target container. This is because you can share 
container objects between containers. 

virtual Boolean Supported On: 

isMoveValid( IContainerObject* moveObject, PM. Motif 

IContainerObject* newParentObject = 0, 

IContainerControl* newContainer = 0, 

IContainerObject* afterObject = 0); 
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moveObjectTo 

Moves the specified object and its descendents to the specified new location. This 
function calls IContainerControl::isMoveValid (p. 187) to determine if the move is 
possible. If an object and its descendents do not already exist in the new location, 
this function moves the object and its descendents to the new container. Returns true 
if the move was valid and successful. 

The parameters are the following: 
moveObject 

The object and all of its descendents (if any) you want to move. 
newParentObject 

The new parent for moveObject. The default is moveObject becomes a 
root-level object (that is, there is no parent). 

newContainer 

The container that is the target of the move operation. The default is the 
container you are calling this function upon (that is, the source container). 


afterObject 

The object in the target container after which you want to place 
moveObject. If newParentObject is 0 and afterObject is 0, moveObject is 
the first object in the container. If newParentObject is not 0 and 
afterObject is 0, moveObject is the first child of newParentObject. 

icon ViewLocations 

The icon view position in workspace coordinates. 


virtual Boolean Supported On: 

moveObjectTo( IContainerObject* moveObject, PM, Motif 

IContainerObject* newParentObject = 0, 

IContainerControl* newContainer = 0, 

IContainerObject* afterObject = 0, 

const IPoint& iconViewLocation = IPoint ( 0 , 

0 )); 

Notification Members 

These INotificationld strings are used for all notifications that IContainerControl provides to its 
observers. 


enableNotification 

Enables the container to send notifications to its observer objects. 
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virtual IContainerControl& 
enableNotification( Boolean enable = true); 


Supported On: 

PM, Motif 


Object Position 

Use these members to manipulate and query an object's position. 

columnUnderPoint 

Retrieves the column under the specified point, in window coordinates. 

IContai nerCol umn* Supported On: 

columnUnderPoint( const IPoint& point) const; PM, Motif Ignored 

convertT oWorkspace 

Converts a rectangle from container window coordinates to workspace coordinates. 

This is valid only for the current view. 

IRectangle 
convertToWorkspace( 

const IRectangle& windowRectangle, 

Boolean rightWindow = false) const; 

detailsObjectRectangle 

Returns the details view rectangle. If you specify a column, this function provides 
the cell in the details view. This rectangle is in container window coordinates. 

If you want the column object's width, use IContainerControl::detailsObjectRectangle 
instead of IContainerColumn::displayWidth. This is because a container details view 
cell is like a rectangle inside of another rectangle: 

• The inner rectangle is the data rectangle of the cell and does not contain the 
required column margin. 

This rectangle's width is either: 

- The value set via IContainerColumn::setDisplayWidth 

- The value queried via IContainerColumn::displayWidth 

• The outer rectangle is the complete cell, including the margins that the container 
control requires. 

This is the value returned by IContainerControl::detailsObjectRectangle. 

The parameters are: 

object The object you want the details view rectangle for. 


Supported On: 

PM, Motif Ignored 
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rightWindow 

If the container is in the details view, use this flag to specify which 
rectangle to return. This will be the rectangle that encompasses all 
columns for an object in either the left or right details view window. If 
you specify true, the rectangle is for the right window. Otherwise, the 
rectangle is for the left window. 

column A column identifying a boundary of a rectangle. 


| IRectangle 

detai 1 sObjectRectangle( 
const IContainerObject* object, 
Boolean rightWindow = false) const; 


@ IRectangle Supported On: 

detailsObjectRectangle( const IContainerObject* object, PM, Motif Ignored 

const IContainerColumn* column) const; 


Supported On: 

PM, Motif Ignored 


iconRectangle 

Returns the rectangle bounding an object's icon. If you specify includeText as true, 
this rectangle also includes the object's text. 


IRectangle 

iconRectangle( const IContainerObject* object. 

Boolean includeText = false) const; 


Supported On: 

PM, Motif Ignored 


_Moves the specified object to a new workspace location within the icon view. 


virtual IContainerControl& 
movelconToj IContainerObject* object, 
const IPoint& point); 


Supported On: 

PM, Motif Ignored 


objectUnderPoint 

Retrieves the object under the specified point, in window coordinates. If the 
container is in the icon view, this function returns the top-most object. 


IContainerObject* 

objectUnderPoint( const IPoint& point) const; 


Supported On: 

PM, Motif Ignored 


textRectangle 

Returns the text rectangle in window coordinates. 
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IRectangle Supported On: 

textRectangle( const IContainerObject* object) const; PM, Motif Ignored 


Overrides 

This class overrides these inherited members. 

The isVisible function that does not use an object for a parameter is an override of 
IWindow::visible, which queries whether the container is visible. 

If an object is specified, the function queries whether the object is visible. 

[J virtual Boolean Supported On: 

isVisible() const; PM, Motif 


Q Bool ean Supported On: 

isVisible( const IContainerObject* object) const; PM. Motif Ignored 

refresh 

[] virtual IContainerControl& Supported On: 

refresh( Boolean immediate = false); PM. Motif Ignored 

Refreshes all objects in the container. If immediate is set to true, the painting is done 
synchronously, that is all container painting is completed before this function returns 
to the caller. If immediate is false, the container painting will occur asynchronously 
and painting may not be completed when the function returns to the caller. 

g virtual IContai nerControl & Supported On: 

refresh( IContainerObject* object, PM, Motif Ignored 

Boolean immediate = false); 

Refreshes an object in the container. If immediate is set to true, the painting is done 
synchronously, that is all container painting is completed before this function returns 
to the caller. If immediate is false, the container painting will occur asynchronously 
and painting may not be completed when the function returns to the caller. 

0 virtual IContai nerControl & Supported On: 

refresh( const IRectangle& inval idRectangle, PM, Motif Ignored 

Boolean immediate); 

Refreshes a specific rectangle in a container. If immediate is set to true, the painting 
is done synchronously, that is all container painting is completed before this function 
returns to the caller. If immediate is false, the container painting will occur 
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asynchronously and painting may not be completed when the function returns to the 
caller. 


0 virtual IContainerControl& Supported On: 

refresh( IWindow::RefreshType type); PM, Motif Ignored 

Refreshes the window based on the IWindoow::RefreshType (Vol. II). 

-Overrides IWindow::sendEvent (Vol. II). 

Q virtual IEventResult Supported On: 

sendEvent( const IEvent& event) const; Motif 


g virtual IEventResult 

sendEvent( unsigned long eventld, 

const IEventParameterl& parameterl = 0, 
const IEventParameter2& parameter2 = 0) const; 


Supported On: 

Motif 


virtual IEventResult 

sendEvent( EventType eventType, 

const IEventParameterl& parameterl = 0, 
const IEventParameter2& parameter2 = 0) const; 


Supported On: 

Motif 


set Backg rou ndCol or 

Sets the background color. 


IContai nerControl & Supported On: 

setBackgroundColor( const IColor& color); Motif 

I_j This function is overridden under Motif so that the parent ScrolledWindow is also 

set to the specified color. 

Querying Object Attributes 

Use these members to query the attributes of an object. 

—Queries whether the specified tree-view node object is currently collapsed. 

Boolean Supported On: 

isCollapsed( const IContainerObject* object) const; PM, Motif Ignored 

-Queries whether the specified object has cursored emphasis. 
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Boolean 

isCursored( const IContainerObject* object) const; 


Supported On: 

PM, Motif Ignored 


isDropOnAble 

Queries whether the specified object is set to receive a direct manipulation drop. 


Boolean Supported On: 

isDropOnAble( const IContai nerObject* object) const; PM, Motif Ignored 

_Queries whether the specified tree-view node object is currently expanded. 


Boolean Supported On: 

isExpanded( const IContai nerObject* object) const; PM, Motif Ignored 

Queries whether the specified object has in-use emphasis. 

Boolean 

isInUse( const IContainerObject* object) const; 

...Queries whether the specified object has selection emphasis 

Boolean Supported On: 

isSelected( const IContai nerObject* object) const; PM, Motif 

.Queries whether the specified object has source emphasis. Source emphasis is a 

visual cue that the object is the source of an operation. Objects being dragged and 
objects with pop-up menus normally display source emphasis. 


Supported On: 

PM, Motif Ignored 


Boolean Supported On: 

isSource( const IContainerObject* object) const; PM, Motif Ignored 

..Queries whether the specified object is a target of direct manipulation. 


Boolean Supported On: 

isTarget( const IContainerObject* object) const; PM, Motif Ignored 

The isVisible function that does not use an object for a parameter is an override of 
IWindow::visible, which queries whether the container is visible. 

If an object is specified, the function queries whether the object is visible. 


[J Boolean 

isVisible( const IContainerObject* object) const; 


Supported On: 

PM, Motif Ignored 
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g virtual Boolean 

isVisible() const; 

.Returns true if the object can be edited. 


Supported On: 

PM, Motif 


Boolean 

isWriteable( const IContainerObject* object) const; 


Supported On: 

PM, Motif Ignored 


Querying the View Port Rectangle 

Use these members to determine the work area relative to either the work space or the window. 


details ViewPortOnWindow 

ReUieves either the right or left work area of a split details view, in window 
coordinates. 


IRectangle Supported On: 

detai 1 sVi ewPortOnWindow( PM, Motif Ignored 

Boolean rightSide = false) const; 

details ViewPortOnWorkspace 

ReUieves either the right or left work area of a split details view, in workspace 
coordinates. 


IRectangle 

detai1sViewPortOnWorkspace( 

Boolean rightSide = false) const; 


Supported On: 

PM, Motif Ignored 


ViewPortOnWindow 

ReUieves the current work area in window coordinates. 


IRectangle 

viewPortOnWindow() const; 

ViewPortOnWorkspace 

ReUieves the current work area in workspace coordinates. 


IRectangle 

viewPortOnWorkspace() const; 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 
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Refresh 

Use these members to refresh the container. 

—Queries the refresh state of the container. If the container immediately displays 
visual changes, true is returned. 


Boolean 

isRefreshOn () const; 


Supported On: 

PM, Motif Ignored 


[J virtual IContainerControl& Supported On: 

refresh ( IContainerObject* object, PM, Motif Ignored 

Boolean immediate = false); 

Refreshes an object in the container. If immediate is set to true, the painting is done 
synchronously, that is all container painting is completed before this function returns 
to the caller. If immediate is false, the container painting will occur asynchronously 
and painting may not be completed when the function returns to the caller. 

| virtual IContai nerControl & Supported On: 

refresh( Boolean immediate = false); PM. Motif Ignored 

Refreshes all objects in the container. If immediate is set to true, the painting is done 
synchronously, that is all container painting is completed before this function returns 
to the caller. If immediate is false, the container painting will occur asynchronously 
and painting may not be completed when the function returns to the caller. 

g virtual IContai nerControl & Supported On: 

refresh( const IRectangle& inval idRectangle, PM, Motif Ignored 

Boolean immediate); 

Refreshes a specific rectangle in a container. If immediate is set to true, the painting 
is done synchronously, that is all container painting is completed before this function 
returns to the caller. If immediate is false, the container painting will occur 
asynchronously and painting may not be completed when the function returns to the 
caller. 

[] virtual IContai nerControl & Supported On: 

refresh( IWindow: :RefreshType type); PM, Motif Ignored 

Refreshes the window based on the IWindoow::RefreshType (Vol. II). 

refreshAIIContainers 

Refreshes all containers. 
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static void Supported On: 

refreshAl1 Containers( Boolean immediate = false); PM, Motif Ignored 

Refreshes all objects in all containers. If immediatee is set to true, the painting is 
done synchronously, that is all container painting is completed before this function 
returns to the caller. If immediate is false, the container painting will occur 
asynchronously and painting may not be completed when the function returns to the 
caller. 


setRefreshOff 

Disables refreshing the container until IContainerControl: :refresh (p. 192) or 
setRefreshOn (p. 197) is called to enable refreshing it. This function sets the 
container's refresh state to off. After you set refresh to off in the container, you must 
call setRefreshOn followed by IContainerControl::refresh to show changes made 
while refresh was set to off. 

virtual IContainerControl& 
setRefreshOff(); 

setRefreshOn 

Enables refreshing the container after changes. This function sets the container's 
refresh state to on. You should also call IContainerControl::refresh after this function 
to show changes made to the container while refresh was set to off. 

virtual IContai nerControl & Supported On: 

setRefreshOn ( Boolean on = true); PM. Motif Ignored 


Supported On: 

PM, Motif Ignored 


Retrieving Objects 

Use these members to retrieve objects in the container. 


containsObject 

If the specified object is in the container, true is returned. 


Boolean 

containsObject( const IContainerObject* object) const; 


Supported On: 

PM, Motif 


cursoredObject 

Returns the object on which the cursor is located. 


virtual IContainerObject* 
cursoredObject() const; 


Supported On: 

PM, Motif Ignored 
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descendentsOf 

Returns the set of all descendents of an object in the tree view. 


ICnrObjectSet Supported On: 

descendentsOf( IContainerObject* parentObject) const; PM, Motif 

immediateDescendentsOf 

Returns the set of immediate descendents only of the specified object in the tree view. 


ICnrObjectSet Supported On: 

immediateDescendentsOf( PM. Motif 

IContainerObject* parentObject) const; 

Returns an object at the specified index or cursor position in the container. 


| virtual IContainerObject* 

objectAt( unsigned long index) const; 


Supported On: 

PM. Motif 


g virtual IContainerObject* 
objectAt( 

const IContainerControl::ObjectCursor& cursor) const; 


Supported On: 

PM. Motif 


0 virtual IContainerObject* 
objectAt( 

const IContainerControl::TextCursor& cursor) const; 
.Returns the number of objects in the container. 


Supported On: 

PM, Motif Ignored 


unsigned long 
objectCount() const; 

.Returns the set of all objects in the container. 


Supported On: 

PM. Motif 


ICnrObjectSet 
objectList() const; 


Supported On: 

PM. Motif 


_Returns the parent of an object in the tree view. If the object does not have a 
parent object, true is returned. 


virtual IContainerObject* 

parentObject( const IContainerObject* childObject) const; 


Supported On: 

PM. Motif 
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Scrolling 

Use these members to scroll the container. 

Scrolls the container both horizontally and vertically. If you specify a nonzero 
horizontalPixels and the container is currently displaying a split details view, 
rightSide determines which pane is scrolled horizontally. 

The parameters are: 
verticalPixels 

The number of pixels to scroll in the vertical direction. 
horizontalPixels 

The number of pixels to scroll in the horizontal direction. 

rightSide If this container is in details view, specify true to scroll the right pane 
and false to scroll the left pane. 


virtual IContainerControl& Supported On: 

scrol 1 ( long verical Pixel s, PM, Motif Ignored 

long horizontalPixels, 

Boolean rightSide = false); 


scrollDetailsHorizontally 

Scrolls either the right or left side of a split details view horizontally. 

The parameters are: 
horizontalPixels 

The number of pixels to scroll in the horizontal direction. 

rightSide Specifies which side to scroll. True indicates the right pane and false 
indicates the left pane. 


virtual IContainerControl& 

scrol1Detai1sHorizontally( long horizontalPixels, 

Boolean rightSide = false); 


Supported On: 

PM, Motif Ignored 


scrollHorizontally 

Scrolls the container horizontally. 

The parameters are: 

pixels The number of pixels to scroll horizontally. 
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rightSide If this container is in details view, specify true to scroll the right pane 
and false to scroll the left pane. 


virtual IContainerControl& 
scrol1Horizontally( long pixels. 

Boolean rightSide = false); 


Supported On: 

PM, Motif Ignored 


scrollToObject 

Scrolls the container to the specified object and, optionally, a specified column into 
the work area. If you specify false for leftJustify, the column is scrolled into the 
work area at the closest border. 


[] virtual IContai nerControl & Supported On: 

scrollToObject( const IContainerObject* object, PM, Motif Ignored 

const IContainerColumn* column, 

Boolean leftJustify = true); 


g virtual IContainerControl & 

scrollToObject( const IContainerObject* object); 


Supported On: 

PM, Motif Ignored 


scrollVertically 

Scrolls the container vertically. 


virtual IContainerControl& 
scrol 1 Verti cal ly( long pixels); 


Supported On: 

PM, Motif Ignored 


Setting Object Attributes 

Use these members to set and remove the attributes of objects. 

-Collapses the descendents of an object in the tree view. 

To modify the icons used for expanding and collapsing the tree view, see 
IContainerControl::setTreeItemIcons (p. 205). 

Note: The parent is not actually being collapsed or expanded. 


virtual IContainerControl& 
collapse( IContainerObject* object); 


Supported On: 

PM, Motif Ignored 
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disableDataUpdate 

Disables direct editing of the text of an object. 

virtual IContainerControl& Supported On: 

disableDatal)pdate( IContainerObject* object); PM. Motif Ignored 

- Disables an object from receiving a drop. No target emphasis is drawn. 

virtual IContai nerControl & Supported On: 

disableDrop( IContainerObject* object); PM. Motif Ignored 

enableDataUpdate 

Enables direct editing of the text of a specified object. In addition, the container 
itself must be in a state that allows direct editing. You can do this by constructing 
the container without the style IContainerControl::readOnly. 

virtual IContai nerControl & Supported On: 

enableDataUpdate( IContainerObject* object, PM. Motif Ignored 

Boolean enable = true); 

-.Enables a specified object to be the target of a drag event. 

virtual IContainerControl& 
enableDrop( IContainerObject* object, 

Boolean enable = true); 

-Expands the tree view to show the descendents of the specified parent object. 

To modify the icons used for expanding and collapsing the tree view, see 
IContainerControl::setTreeItemIcons (p. 205). 

virtual IContainerControl& 
expand( IContainerObject* object); 

-.Makes a specified object invisible by filtering it out of the container. 

virtual IContainerControl& 
hideObject( IContainerObject* object); 

hideSourceEmphasis 

Removes source emphasis. If you specify an object, this function removes the 
emphasis from that object. Otherwise, it removes source emphasis from the container 
itself. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 
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| virtual IContainerControl& 

hideSourceEmphasis( IContainerObject* object); 


Supported On: 

PM, Motif Ignored 


2 virtual IContainerControl & 
hideSourceEmphasis(); 


Supported On: 

PM, Motif Ignored 


Q virtual IContai nerControl & Supported On: 

refresh( Boolean immediate = false); PM, Motif Ignored 

Refreshes all objects in the container. If immediate is set to true, the painting is done 
synchronously, that is all container painting is completed before this function returns 
to the caller. If immediate is false, the container painting will occur asynchronously 
and painting may not be completed when the function returns to the caller. 

| virtual IContai nerControl & Supported On: 

refresh( IContainerObject* object, PM, Motif Ignored 

Boolean immediate = false); 

Refreshes an object in the container. If immediate is set to true, the painting is done 
synchronously, that is all container painting is completed before this function returns 
to the caller. If immediate is false, the container painting will occur asynchronously 
and painting may not be completed when the function returns to the caller. 

0 virtual IContai nerControl & Supported On: 

refresh( const IRectangle& inval idRectangle, PM, Motif Ignored 

Boolean immediate); 

Refreshes a specific rectangle in a container. If immediate is set to true, the painting 
is done synchronously, that is all container painting is completed before this function 
returns to the caller. If immediate is false, the container painting will occur 
asynchronously and painting may not be completed when the function returns to the 
caller. 


J] virtual IContai nerControl & 

refresh( IWindow::RefreshType type); 


Supported On: 

PM, Motif Ignored 


Refreshes the window based on the IWindoow::RefreshType (Vol. II). 


—Removes in-use emphasis from the specified object. 


virtual IContainerControl& 
removelnUsej IContainerObject* object); 


Supported On: 

PM, Motif Ignored 
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removeSelected 

Removes selection emphasis from the specified object. 


IPM 


virtual IContainerControl& Supported On: 

removeSelected( IContainerObject* object); PM. Motif 

A single selection container or a container in tree view must always have exactly one 
object selected. You cannot remove selection emphasis from the only selected object 
in these cases. 


Gives the specified object cursor emphasis. 


virtual IContainerControl& 

setCursor( IContainerObject* object); 

Gives the specified object in-use emphasis. 


Supported On: 

PM. Motif Ignored 


virtual IContainerControl& 

setInUse( IContainerObject* object, 

Bool ean i nllse = true); 

—Gives the specified object selection emphasis. 


Supported On: 

PM. Motif Ignored 


IPM 


virtual IContai nerControl & Supported On: 

setSelected( IContainerObject* object, PM. Motif 

Boolean select = true); 

A single selection container or a container in tree view must always have exactly one 
object selected. You cannot remove selection emphasis from the only selected object 
in these cases. 


—Shows the specified object that is currently invisible or filtered from the container. 


virtual IContainerControl& 

showObject( IContainerObject* object, 
Boolean visible = true); 


Supported On: 

PM, Motif 


showSourceEmphasis 

Draws source emphasis. If you specify an object, the emphasis is drawn around the 
object. Otherwise, the container itself gets the source emphasis. 


| virtual IContainerControl& 

showSourceEmphasis( Boolean source = true); 


Supported On: 

PM, Motif Ignored 
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2 virtual IContainerControl& 

showSourceEmphasis( IContainerObject* object, 
Boolean source = true); 


Supported On: 

PM, Motif Ignored 


Sorting Objects 

Use these members to provide sorting in the container. 

- Compares two specified strings consisting of a national character set. Use this 
function for implementing National Language Support (NLS). 


static long 

nlsCompare( const char* textl, 
const char* text2); 


Supported On: 

PM. Motif 


Sorts the container using a user-defined sort function, IContainerControI::CompareFn 
(p. 223). 


virtual IContainerControl& 

sort( const IContainerControl::CompareFn& sortObject); 


Supported On: 

PM. Motif 


sortBylconText 

Sorts the container by the icon's text. 


virtual IContainerControl& 
sortByIconText( Boolean ascending = true); 


Supported On: 

PM. Motif 


Styles 

These style members provide valid container styles for IContainerControl: :setDefaultStyle and for 
the constructor of the IContainerControl (p. 163) class. 


convertToGUIStyle 

p. Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are define by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 


virtual unsigned long 
convertToGUIStyle( const IBitFlag& style, 

Boolean extendedOnly = false) const; 


Supported On: 

PM. Motif 


—Returns the default style. The default style is classDefaultStyle (p. 214) unless you 
have changed it using setDefaultStyle (p. 205). 
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static Style 
defaul tStyle(); 


setDefaultStyle 

Sets the default style for all subsequent containers. 

style Use the styles provided by IContainerControl: :Style (p. 

the default style. 


static void 

setDefaultStyle( const Style& style); 


Tree View Functions 

Use these members in the tree view. 

_ Collapses all nodes of a tree view. 


virtual IContainerControl& 
collapseTree(); 

_Expands all nodes of a tree view. 


virtual IContainerControl& 
expandTree(); 

...Does not show the lines connecting parents to children's records. 


virtual IContainerControl& 
hideTreeLine(); 

setT reeExpandlconSize 

Changes the size of the expanded and collapsed icons. 


virtual IContainerControl& 

setTreeExpandIconSize( const ISize& sizelcon); 

setTreeltemlcons 

Sets the expanded and collapsed icons for a tree view. 


Supported On: 

PM, Motif 


233) to specify 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif Ignored 
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| virtual IContainerControl& 

setTreeltemlcons( const IPointerHandle& expanded, 
const IPointerHandle& collapsed); 


Supported On: 

PM, Motif 


| virtual IContainerControl & 

setTreeltemlcons( const IResourceId& expanded, 
const IResourceId& collapsed); 


Supported On: 

PM, Motif 


setT reeViewIndent 

Sets the distance that children are offset horizontally from their parent. 


virtual IContainerControl& 
setTreeViewIndent( long indentPixels = - 1); 


Supported On: 

PM, Motif 


showTreeLine 

Shows the lines connecting parents to children's records. 


virtual IContainerControl& 
showTreeLine( long treeLinePixelWidth = - 1); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 
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Protected Functions 
Compound Control Method 

These members return miscellaneous informaton for this compound control. 

_ Returns the top, that is, the oldest ancestor, window system control of the window 
controls created by this object. Use the returned handle to show this object and 
destroy the window system controls during object destruction. 

virtual IWindowHandle 
topHandle() const; 

Constructors 

You can construct and destruct objects of this class. 

Note: The AIX version does not support constructing objects from a loaded dialog template or 
from an existing container control's window handle. 


Supported On: 

Motif 


IContainerControl (); Supported On: 

PM, Motif 

Default consttuctor which accepts no arguments. 

Event-Handling Implementation 

Event-handling implementation members perform perocessing that allows handlers to receive 
GUI events and to route these events. 


registerCallbacks 

Registers all possible callbacks and X event handlers to this object for events it might 
receive. IHandler derived classes later determine which events they will process. 

If classes you derive override the registerCallbacks member function, the override 
must call Inherited::registerCallbacks to register the applicable callbacks and X event 
handlers. 

void Supported On: 

regi sterCall backs (); Motif 
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unregisterCallbacks 

Unregisters Motif callbacks for the widgets created during the construction of objects 
of this class. 


voi d 

unregisterCal1 backs(); 


Supported On: 

Motif 


Implementation 

These members implement the class. 

-Returns an attribute mask for the specified object. 


unsigned long 

attributes( const IContainerObject* object) const; 


Supported On: 

PM. Motif 


baseRecordSize 

Returns the size of the RECORDCORE portion of the objects stored in a container. 


Supported On: 

PM. Motif 

calcMinimumSize 

Returns a minimum size for the container. 


virtual unsigned long 
baseRecordSize(); 


virtual ISize Supported On: 

calcMinimumSizeO const; PM. Motif 

Returns a column matching the command criteria. 


IContai nerCol unin* Supported On: 

column( IContai nerCol umn* column, PM. Motif 

unsigned long command, 

Boolean visible); 


containerAttributes 

Returns the current container attribute mask. 


unsigned long 

containerAttributes() const; 


Supported On: 

PM. Motif 


-.Returns the key used to control access when updating the container. The key acts 
as a semaphore to the container updates. 
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static IPrivateResource& 
containerKey(); 

-...Returns the list of containers in this application. 


static ICnrControlList& 
containerList(); 


hwndAllocation 

Returns the container used for object allocation. 

static IWindowHandle 
hwndAl1ocation (); 

-..Updates the attributes of the specified object. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


virtual void Supported On: 

setAttributes( IContainerObject* object, PM, Motif 

unsigned long attributeToTurnOn, 
unsigned long attributeToTurnOff); 


setContainerAttributes 

Sets the atttibutes into the container control. 


virtual void Supported On: 

setContai nerAttri butes ( PM, Motif 

unsigned long attributeToTurnOff, 
unsigned long attributeToTurnOn); 

_Sets the specified object to the specified emphasis atttibute. 


virtual void Supported On: 

setEmphasis( IContai nerObject* object, PM, Motif 

unsigned long emphasisAttribute. 

Boolean setOn = true); 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 
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Public Data 
Attributes 

These attribute members provide valid container styles for IContainerControl::setDefaultAttribute 
and for the constructor of the IContainerControl (p. 163) class. 

alignTitleCentered 

Centers the container title. 


static const Attribute Supported On: 

alignTitleCentered; PM. Motif 

_Left-justifies the container title. 


static const Attribute 
al ignTitleLeft; 

alignTitleRight 

Right-justifies the container title. 

static const Attribute 
alignTitleRight; 


class Detail It Attribute 

Specifies the original default attribute for this class, which is orderedTargetEmphasis I 
detailsViewTitles I visibleTreeLine I readOnlyTitle I iconView. 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


static const Attribute Supported On: 

cl assDefaul tAttri bute; PM. Motif 

-.Shows the details view of the container. 


static const Attribute 
detai1sView; 


Supported On: 

PM. Motif 


detailsViewTitles 

Shows the details view titles. 


static const Attribute 
detailsViewTitles; 


Supported On: 

PM. Motif 
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_Shows the flowed view of the container. 

Note: This attribute is only valid when combined with the nameView attribute or the 
textView attribute. 


static const Attribute 
flowedView; 


Supported On: 

PM, Motif 


handleDrawBackground 

Causes draw-background messages to be dispatched to objects of classes derived from 
ICnrDrawHandler. 

Note: The AIX release does not support this attribute because AIX does not support 
the ICnrDrawHandle. 

static const Attribute Supported On: 

handleDrawBackground; PM, Motif 


handleDrawItem 

Causes draw-item messages to be dispatched to objects of classes derived from 
ICnrDrawHandler. 

Note: The AIX release does not support this attribute because AIX does not support 
the ICnrDrawHandle. 

static const Attribute Supported On: 

handleDrawItem; PM, Motif 

Shows the icon view of the container. 


static const Attribute 
iconView; 

Shows mini icons. 

static const Attribute 
mini Icons; 

mixedTargetEmphasis 

Sets the mixed-target emphasis. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


static const Attribute 
mixedTargetEmphasis; 


Supported On: 

PM, Motif 
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-Shows the name view of the container. 


static const Attribute 
nameView; 


orderedTargetEmphasis 

Sets the ordered-target emphasis. 

static const Attribute 
orderedTargetEmphasis; 

- Disables the editing of the container title. 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


static const Attribute 
readOnlyTitle; 

..Shows the text view of the container. 


Supported On: 

PM. Motif 


static const Attribute 
textView; 


Supported On: 

PM. Motif 


titleSeparator 

Adds a separator line after the title. 


static const Attribute 
titleSeparator; 

Shows the tree view of the container. 


Supported On: 

PM. Motif 


static const Attribute 
treeView; 

-Shows the container title. 


Supported On: 

PM. Motif 


static const Attribute 
vi si bl eTitle; 


Supported On: 

PM. Motif 


visibleTreeLine 

Shows the tree line in the tree view. 


static const Attribute 
visibleTreeLine; 


Supported On: 

PM. Motif 
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Notification Members 

These INotificationld strings are used for all notifications that IContainerControl provides to its 
observers. 

.Notification identifier provided to observers when objects are added to a container. 
IContainerControl provides an unsigned long value in the 

INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value indicates how many objects were added. 

static INotificationld const Supported On: 

add Id; PM, Motif 

detailsViewTitlesId 

Notification identifier provided to observers when the visibility of the container 
details view titles changes. IContainerControl provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is true if the details view titles are now visible and false if the details view 
titles are invisible. 


static INotificationld const Supported On: 

detailsViewTitlesId; PM. Motif 

..Notification identifier provided to observers when an item in the container is double 
clicked, or the user presses the enter key. IContainerControl provides the enter event 
in the INotificationEvent: :eventData (Vol. I) field of the INotificationEvent (Vol. I). 


static INotificationld const Supported On: 

enterld; PM, Motif 

...Notification identifier provided to observers when objects are removed from a 
container. IContainerControl provides an unsigned long value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value indicates how many objects were removed. 

static INotificationld const Supported On: 

removeld; PM, Motif 

...Notification identifier provided to observers when a container item's selection state 
changes. IContainerControl provides the emphasis event in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 


static INotificationld const 
selectld; 


Supported On: 

PM, Motif 
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_ Notification identifier provided to observers when the text of the title changes in the 
container control. IContainerControl provides a pointer to the new title text string in 
the INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

titleld; PM. Motif 

-.Notification identifier provided to observers when the visibility of the container title 
changes. IContainerControl provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is true if the title is now visible and false if the title is invisible. 

static INotificationld const Supported On: 

ti tl eVi si bl eld; PM. Motif 


Styles 

These style members provide valid container styles for IContainerControl: :setDefaultStyle and for 
the constructor of the IContainerControl (p. 163) class. 

- Automatically positions objects added to the container in the icon view. 

static const Style Supported On: 

autoPosition; PM. Motif 


classDefaultStyle 

Specifies the original default style for this class, which is singleSelection I 
IWindow:: visible. 

static const Style Supported On: 

classDefaultStyle; PM. Motif 

extendedSelection 

Specifies that the container use extended selection. Extended selection is an enhanced 
version of single selection that lets the user select discontiguous sets of container 
items. 


static const Style 
extendedSelection; 


Supported On: 

PM. Motif 
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multipleSelection 

Specifies that the container use multiple selection. Multiple selection is a mode that 
allows the user unrestricted selection of objects. 

static const Style Supported On: 

multipleSelection; PM, Motif 

noSharedObjects 

Specifies that this container's objects are not shared with other containers. This will 
provide better performance when the container is deleted or deleteAllObjects is called. 


static const Style Supported On: 

noSharedObjects; PM. Motif 

-Specifies that the text in the container cannot be edited. If this style is set, the user 
cannot edit anything in the container regardless of calls to the following: 

• enableDataUpdate on the container object 

• enableTitleUpdate on the container object 

• enableDataUpdate on an IContainerColumn object 

• enableHeadingUpdate on an IContainerColumn object 


static const Style 
readonly; 


Supported On: 

PM, Motif 


singleSelection 

Specifies the container use single selection. In this mode, the user (or your code) can 
only select a single object at a time. Selecting a new object removes the selection 
from a prior object. In a single-selection container one object is always selected. If 
you remove an object with selection emphasis, the container selects another object. 

static const Style Supported On: 

singleSelection; PM, Motif 


verifyPointers 

Validates that container objects exist. If you specify this style, the presentation 
system checks that an object exists in the collection prior to using it. If a container 
record does not exist, an IAccessError exception is thrown. 

static const Style Supported On: 

veri fyPoi nters; PM, Motif 
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Inherited Public Data 


IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderCoiorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

dipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

ddeteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IContainerControl contains the following nested classes: 

IContainerControl::ObjectCursor (see page 229) 
IContainerControl: :CompareFn (see page 223) 
IContainerControl::Attribute (see page 218) 
IContainerControl::ColumnCursor (see page 219) 
IContainerControl: :FilterFn (see page 225) 
IContainerControl::TextCursor (see page 234) 
IContainerControl::Style (see page 233) 
IContainerControl:Iterator (see page 227) 
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TitleAlignment 

TitleAlignment { 
left, 
right, 
centered 
}; 


Use these enumerators to specify the type of alignment for a title: 

left 

Left-justifies the container titles. 


right 

Right-justifies the container titles. 

centered 

Centers the container titles. 


EnumerationOrder 


EnumerationOrder 
itemOrder, 
zOrder 
}; 


{ 


Use these enumerators to specify the order in which icons are enumerated: 

itemOrder 

Enumerate container records in item order; lowest to highest. Item order is 
similar to the order in which the records were added to the container, except 
you can explicitly insert records into the item order. 

zOrder 

Enumerate container records by z-order, first to last. 

zOrder is the order in which icons appear in the icon view of the container: 
left to right, top to bottom, and then top icon to bottom icon as described 
above. 

Note: This enumerator is only valid for the icon view. 
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IContainerControl:: Attribute 


IBase 

IBitFlag 

IContainerControl:: Attribute 


_.None. 

—icnrctl.hpp 

The nested class IContainerControl::Attribute provides a set of valid attributes for the 
IContainerControl (p. 163) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerControl::ColumnCursor 


IBase 

IVBase 

IContainerControl:: ColumnCursor 


_.None. 


-icnrctl.hpp 

Member 

Page 

Constructor 

220 

ColumnCursor 

220 

current 

219 

first 

219 

invalidate 

221 

is Valid 

222 

last 

220 

next 

220 


Member 

Page 

previous 

220 

setCurrent 

220 

setToFirst 

221 

setToLast 

221 

setToNext 

221 

setToPrevious 

221 

“ColumnCursor 

221 


Objects of the IContainerControl::ColumnCursor class navigate through the container's 
details view columns. 

1 The left-most column that the Container widget maintains automatically is never 

accessed by the ColumnCursor. 


Public Functions 
Column Retrieval 

Use these members to move the cursor and retrieve columns. 

Returns the current column of this cursor. 

virtual IContainerColumn* Supported On: 

current() const; PM, Motif 

Points to and returns the first column in the container. If there are no objects in the 
container, 0 is returned. This function validates a cursor that was set invalid as a 
result of adding or removing columns from the container. 
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virtual IContainerColumn* Supported On: 

first(); PM, Motif 

Points to and returns the last column in the container. Returns 0 if there are no 
columns in the container. This function validates a cursor that was set invalid as a 
result of adding or removing columns from the container. 

virtual IContai nerCol umn* Supported On: 

lastQ; PM, Motif 

Points to and returns the next or first column in the container. If the cursor has 
reached the end of the list of columns in the container, 0 is returned. 


virtual IContai nerCol umn* Supported On: 

nextQ; PM, Motif 

.Points to and returns the previous or last column in container. 


virtual IContai nerCol umn* Supported On: 

previousQ; PM, Motif 

... Sets the cursor to point to the specified column and validates the cursor. This 
function does not check for visibility. 


virtual ColumnCursor& 

setCurrent( const IContainerColumn* currentColumn); 


Supported On: 

PM. Motif 


Constructors 

You can construct and destruct objects of this class. 

ColumnCursor 

You can only construct objects of this class by using a cursor to iterate through all 
columns in the container meeting the visibility criteria (all columns or visible columns 
only). You must specify the following: 

• The container where navigation is to occur 

• Optionally, a Boolean indicating whether all columns, or only visible columns, 
are navigated 

ColumnCursor( const IContainerControl& container. Supported On: 

Boolean visibleOnly = false); PM, Motif 
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ColumnCursor 


virtual 

"ColumnCursor(); 


Supported On: 

PM, Motif 


Cursor Movement 

Use these members to move the cursor and retrieve columns. 

_ Points to the first column in the container. If there are no objects in the container, 
false is returned. This function validates a cursor that was set invalid as a result of 
adding or removing columns from the container. 

virtual Boolean Supported On: 

setToFirstO; PM, Motif 

_ Points to the last column in the container. If there is a last column, true is returned. 
Otherwise, false is returned. 

virtual Boolean Supported On: 

setToLast(); PM, Motif 

_ Points to the next column in the container. If the cursor does not point to a column, 
this function is the same as setToFirst. The cursor does not point to a column when 
it is initially created. In other words, setToNext on a new cursor is the same as 
setToFirst. 


virtual Boolean 
setToNext(); 


Supported On: 

PM, Motif 


setToPrevious 

Points to the previous or last column in the container. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM, Motif 


Cursor Validation 

Use these members to validate the cursor. 
_Flags the cursor as not valid. 


virtual ColumnCursor& 
inval idate(); 


Supported On: 

PM, Motif 
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..Queries whether the cursor is valid. 

The cursor is not valid if any of the following occur: 

• You add a column after you created the cursor. 

• You remove a column after you created the cursor. 

• The last operation on the cursor put it into an undefined state. 

For example, calling setToNext when the cursor is pointing to the last object in the 
container, causes the cursor to be not valid. 

virtual Boolean Supported On: 

isValid() const; PM. Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerControl::CompareFn 


IBase 

IVBase 

IContainerControl:: CompareFn 


_.None. 


_icnrctl.hpp 


Member 

Page 

Member 

Page 

Constructor 

223 

isEqual 

224 

CompareFn 

223 

'CompareFn 

224 


Objects of the IContainerControl::CompareFn class provide a sort function for 
container objects. The container uses these objects to sort its contents. The class 
provides this sorting function by passing the compare function multiple sets of two 
objects. The compare function indicates whether the objects are equal or if one is 
before the other. 

When the container calls IContainerControl::sort (p. 204), an 

IContainerControl ::CompareFn object is passed as input to this function. Thereafter, 
the container calls IContainerControl::CompareFn::isEqual (p. 224) as needed to sort 
each container object. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

_ Default constructor. 

CompareFn (); Supported On: 

PM, Motif 
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CompareFn 


virtual 

'CompareFn(); 


Supported On: 

PM, Motif 


Object Sorting 

Use these members to compare objects in the container. 

-Returns the result of an equivalency test between objectl and object2 in the 
specified container. The results indicate the following: 

Less than 0 The first object ( objectl ) is less than the second object ( object2 ). 
0 The first object is equal to the second object. 

Greater than 0 The first object is greater than the second object. 


virtual int Supported On: 

isEqual( IContainerObject* objectl, PM. Motif 

IContainerObject* object2, 

IContainerControl* container) const = 0; 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerControl "FilterFn 


IBase 

IVBase 

IContainerControl: :FilterFn 


_.None. 


_icnrctl.hpp 


Member 

Page 

Member 

Page 

Constructor 

225 

isMemberOf 

226 

FilterFn 

225 
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226 


Objects of the IContainerControl::FilterFn class provide a filter function for container 
objects. The container uses a FilterFn object to show a subset of the existing 
container objects. The class provides this sorting function based on a call to isEqual 
on the filter function. 

When the container calls IContainerControl::filter (p. 184), an 

IContainerControl::FilterFn object is passed as input to this function. Thereafter, the 
container calls IContainerControl::FilterFn_isMemberOf (p. 226) as needed to filter 
each container object. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

Default constructor. 

FilterFn(); Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


IContainerControl ::CompareFn 225 







IContainerControl: :FilterFn 


TilterFn 


virtual 

'FilterFnO ; 


Supported On: 

PM, Motif 


Object Filtering 

Use these members to filter objects from the container. 

_If the specified object is to remain in the container, true is returned. If the object is 
to be removed, false is returned. 


virtual Boolean 

isMemberOf( IContainerObject* object, 

IContainerControl* container) const = 0; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerControl: iterator 


IBase 

IVBase 

IContainerControl: iterator 


_.None. 


_icnrctl.hpp 


Member 

Page 

Member 

Page 

Constructor 

227 

Iterator 

227 

applyTo 

228 

'Iterator 

228 


Objects of the IContainerControl "Iterator class apply a function to the container's 
objects. To perform a function on the objects of the container, derive a class from 
IContainerControl "Iterator and implement the behavior of 
IContainerControl::Iterator::applyTo (p. 228). Next, call 

IContainerControl::allObjectsDo (p. 185) with an object of this class. allObjectsDo 
calls applyTo on each object until one of the following occurs: 

• IContainerControl::Iterator::applyTo returns false. 

• IContainerControl::allObjectsDo has called applyTo for all the objects in the 
container. 


Public Functions 
Constructors 

You cannot construct objects of this class because it is an abstract base class. 

...You can not construct objects of this class because it is an abstract base class. 

Iterator(); Supported On: 

PM, Motif 
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Iterator 


virtual 

"IteratorO; 


Supported On: 

PM, Motif 


Filter Behavior 

Use these members apply a behavior to all objects in a container. 

_If the iteration is to continue, true is returned. If the iteration is to stop, false is 
returned. 


virtual Boolean 

applyTo( IContainerObject* object) = 0; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerControl: :ObjectCursor 


IBase 

IVBase 

IContainerControl:: ObjectCursor 


_.None. 


_Jcnrctl.hpp 
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Objects of the IContainerControl::ObjectCursor class iterate the container by finding 
objects based on the selection criteria established during construction of the cursor. 
The cursor is only valid until objects are added or removed from the container. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ObjectCursor 

0 ObjectCursor( Supported On: 

const IContainerControl& container, PM, Motif 

IContainerObject::Emphasis emphasis = 

IContainerObject::none, 

EnumerationOrder enumeration = itemOrder); 

Construct an object of this class to iterate all records either: 

• In the container 
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• Meeting the emphasis selection criteria 

Optionally, you can specify whether to iterate records in item order (the default) or 
z-order. 


5 ObjectCursor( const IContainerControl& container. Supported On: 

const IContainerObject* parentObject, PM, Motif 

Boolean al1Descendents = false); 

Construct an object of this class to iterate all objects having the specified object as a 
parent. Optionally, you can specify whether to iterate just the immediate child 
objects or all descendents of the specified parent. 

ObjectCursor 


virtual 

'ObjectCursorO; 


Supported On: 

PM, Motif 


Cursor Movement 

Use these members to control cursor movement based on the type of objects indicated in the 
construction of the cursor. 

_ Points to the first object in the container. If there are no objects in the container, 
false is returned. This function validates a cursor that was set invalid as a result of 
adding or removing objects from the container. 


virtual Boolean Supported On: 

setToFirstO; PM, Motif 

...Points to the last object in the container. If there is a last object, true is returned. 
Otherwise, false is returned. 


virtual Boolean Supported On: 

setToLast(); PM, Motif 

.Points to the next object in the container. If the cursor does not point to an object, 

this function is the same as setToFirst. The cursor does not point to an object when 
it is initially created. In other words, setToNext on a new cursor is the same as 
setToFirst. 

virtual Boolean Supported On: 

setToNext 0; PM, Motif 
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setToPrevious 

Points to the previous or last object in the container. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM, Motif 


Cursor Validation 

Use these members to validate the cursor. 
_Flags the cursor as not valid. 


virtual ObjectCursor& Supported On: 

invalidateO; PM. Motif 

.Queries whether the cursor is valid. The cursor is not valid if any of the following 

occur: 

• You add a column after you created the cursor. 

• You remove a column after you created the cursor. 

• The last operation on the cursor put it into an undefined state. 

For example, calling setToNext when the cursor is pointing to the last object in the 
container, causes the cursor to be not valid. 


virtual Boolean 
isValid() const; 


Supported On: 

PM, Motif 


Object Retrieval 

Use these members to retrieve objects. 

Returns the current object of this cursor. 

virtual IContainerObject* Supported On: 

current() const; PM, Motif 

Points to and returns the first object in the container that meets the criteria 
established during the construction of the cursor. If there are no objects in the 
container, 0 is returned. This function validates a cursor that was set invalid as a 
result of adding or removing columns from the container. 

virtual IContai nerObject* Supported On: 

first(); PM, Motif 
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Points to and returns the last object in the container. Returns 0 if there are no 
objects in the container. This function validates a cursor that was set invalid as a 
result of adding or removing objects from the container. 

virtual IContainerObject* Supported On: 

lastQ; PM. Motif 

Points to and returns the next or first object in the container. If the cursor has 
reached the end of the list of objects in the container, 0 is returned. 


virtual IContai nerObject* Supported On: 

nextQ; PM. Motif 

Points to and returns the previous or last object in the container. 


virtual IContai nerObject* Supported On: 

previous(); PM. Motif 

... Sets the cursor to point to the specified object and validates the cursor. This 
function does not check for visibility. 


virtual ObjectCursor& 

setCurrent( const IContainerObject* currentObject); 


Supported On: 

PM. Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerControl: :Style 


IBase 

IBitFlag 

IContainerControl:: Style 


_.None. 

_ icnrctl.hpp 

The nested class IContainerControl::Style provides a set of valid styles for the 
IContainerControl (p. 163) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerControl::TextCursor 


IBase 

IVBase 

IContainerControl: :TextCursor 


_.None. 
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Objects of the IContainerControl::TextCursor class iterate through the container and 
find objects containing a specified text string. You specify this text string when 
creating the text cursor. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

_ You can construct objects of this class by specifying a text string to search the 
container for. Optionally, you can specify that the search return: 

• A case sensitive match only 

• A match only when the text is the first in the record 

• An exact match of the text string only 

When you construct a TextCursor, it is only valid for the objects shown in the 
currently displayed container view. For example, if you construct a TextCursor while 
the container is displaying the icon view and you want the application to iterate a 
TextCursor for children in a tree view, you must do the following: 
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• Switch the container to the tree view 

• Create a new TextCursor 

If you create a details view TextCursor, it searches all the text columns for the 
specified string. 


TextCursor( const IContainerControl & container, Supported On: 

const char* text, PM, Motif 

Boolean isCaseSensitive = true. 

Boolean isFirstlnRecord = false. 

Boolean isExactMatch = false); 

TextCursor 


virtual 

TextCursor(); 


Supported On: 

PM, Motif 


Cursor Movement 

Use these members to position the text cursor. 

^Points to the first object in the container with the matching text. If there are no 
objects in the container, false is returned. This function validates a cursor that was 
set not valid as a result of adding or removing objects from the container. 

virtual Boolean Supported On: 

setToFirstO; PM, Motif 

_ Points to the last object in the container with the matching text. If there is a last 
object, true is returned. Otherwise, false is returned. 

virtual Boolean Supported On: 

setToLast(); PM, Motif 

_ Points to the next or first object in the container with the matching text. If the 
cursor does not point to an object, this function is the same as setToFirst. The cursor 
does not point to an object when it is initially created. In other words, setToNext on 
a new cursor is the same as setToFirst. 


virtual Boolean 
setToNext(); 


Supported On: 

PM, Motif 
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setToPrevious 

Points to the previous or last object in the container. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM, Motif 


Cursor Validation 

Use these members to validate the cursor. 
_Flags the cursor as not valid. 


virtual TextCursor& Supported On: 

invalidate!); PM. Motif 

..Queries whether the cursor is pointing to a valid object. The cursor is not valid if 
any of the following occur: 

• You add a column after you created the cursor. 

• You remove a column after you created the cursor. 

• The last operation on the cursor put it into an undefined state. 

For example, calling setToNext when the cursor is pointing to the last object in the 
container, causes the cursor to be not valid. 


virtual Boolean 
isVal id() const; 


Supported On: 

PM, Motif 


Object Retrieval 

Use these members to retrieve objects using a text cursor. 
Returns the current object of this cursor. 


virtual IContainerObject* Supported On: 

current!) const; PM, Motif 

Points to and returns the first object in the container with the matching text. If there 
are no objects in the container, 0 is returned. This function validates a cursor that 
was set invalid as a result of adding or removing columns from the container. 


virtual IContai nerObject* Supported On: 

first!); PM, Motif 
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Points to an returns the last object in the container with matching text. Returns 0 if 
there are no object in the container. This function will validate a cursor that was set 
invalid as a result of adding or removing an object from the container. 

virtual IContainerObject* Supported On: 

last(); PM, Motif 

Points to and returns the next or first object in the container with the matching text. 

If the cursor has reached the end of the list of objects in the container, 0 is returned. 

virtual IContai nerObject* Supported On: 

next(); PM, Motif 

...Points to and returns the previous or last object in the container with the matching 
text. 


virtual IContai nerObject* Supported On: 

previous(); PM, Motif 

...Sets the cursor to point to the specified object. 


virtual TextCursor& 

setCurrent( const IContainerObject* currentObject); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerControlNotifyHandler 


IBase 

IVBase 

IHandler 

I Windo wN otify Handler 
IContainerControlNotifyHandler 


_.None. 

_icnrnhdr.hpp 


Member Page 

Constructor 238 

dispatchHandlerEvent 239 

"IContainerControlN otifyHandler 239 


Instances of the IContainerControlNotifyHandler class process events for all classes of 
containers. 

This class is designed to handle events that require the container class to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

Use these functions to construct and destruct objects of the IContainerControlNotifyHandler class. 


IContainerControlNotifyHandler 

Default constructor. 


IContainerControlNotifyHandler(); 


Supported On: 

PM, Motif 
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IContainerControlNotifyHandler 


virtual 

'IContai nerControlNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

This function evaluates the event to determine if it is appropriate for this handler object to 
process. 

dispatchHandlerEvent 

If any of the following events are received, the container control observers are 
notified: 

• remove object event 

• add object event 

• select event 

• enter event 

• title visible event 

• details view title event 

• title event 

virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 
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Inherited Protected Functions 


IWindowNotify Handler 

dispatchHandlerEvent 




IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IContainerObject 


IBase 

IVBase 

IContainerObject 


_.None. 




_.icnrobj.hpp 




Member 

Page 

Member 

Page 

Constructor 

242 

isRefreshOn 

247 

baseRecord 

250 

isVisible 

248 

decrementU seCount 

250 

isWriteable 

248 

disableDataUpdate 

246 

objectCopy 

245 

disableDrop 

246 

operator == 

245 

enableDataUpdate 

246 

operator delete 

245 

enableDrop 

246 

operator new 

245 

handleCursoredChange 

243 

refresh 

248 

handlelnuseChange 

244 

removelnUse 

248 

handleOpen 

244 

setAttributes 

251 

handleSelectedChange 

244 

setBase 

251 

handleTreeCollapse 

244 

setClosed 

248 

handleTreeExpand 

244 

setEmphasis 

251 

helpld 

245 

setlcon 

248 

hide 

247 

setlconText 

249 

icon 

247 

setlnUse 

249 

iconText 

247 

setOpen 

249 

incrementU seCount 

250 

setRefreshOff 

249 

initialize 

250 

setRefreshOn 

249 

isAttribute 

251 

show 

249 

isDropOnAble 

247 

useCount 

251 

isInUse 

247 

“IContainerObj ect 

243 

isOpen 

247 




IContainerObject is a required base class for all objects stored in a container. You 
must create all objects of this class using operator new, which is overloaded in this 
class to provide the storage allocation required by the underlying presentation 
system’s container control. 

You can use an IContainerObject object, as is, for all container views except the 
details view. For the details view, you must derive a class from IContainerObject to 
support additional data. If you do, the additional data must be the following: 
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IContainerObject 


• Contiguous with the data of this class 

• One of the supported types defined by IContainerColumn (p. 145) 

Note: You can only edit the string type. We recommend that you use the class 
IString (Vol. I) to store text data in a derived object class. 

We also recommend that you use a resource library to load icons because a resource 
library can do the following: 

• Satisfying multiple requests for the same icon with a single load 

• Manage multiple references to the same object, such that actual icon deletion 
occurs when the use count reaches 0 

You can add IContainerObjects to multiple containers at the same time. When using 
functions in this class to modify an object's characteristics, the functions do so in all 
containers that hold the object. This is true only when the IContainerControl 
parameter for these functions is 0. IContainerControl (p. 163) provides functions that 
you can use to modify certain attributes of an object in a single container. 

You cannot add the same container object twice in a container. OS/2 Presentation 
Manager keeps pointers to place the record in the container relative to other records. 
Presentation Manager does not let you add the same record twice. An IGUIErrorlnfo 
is thrown if you try. You can create another object of this container object using the 
IContainer copy constructor and add that object to the container. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IContainerObject 

[J IContainerObjectO; Supported On: 

PM. Motif 

The default constructor which accepts no parameters. 

2 IContainerObject( const IString& string. Supported On: 

const IPointerHandle& iconHandle = 0); PM. Motif 

Construct an IContainerObject object by providing an IString (Vol. I) for text and an 
IPointerHandle (Vol. II) for the icon. 
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g IContainerObject( const IString& string. Supported On: 

const IResourceId& iconld); PM, Motif 

Construct an IContainerObject object by providing an IString for text and an 
IResourceld (Vol. II) for the icon. 

0 IContainerObject( const IResourceId& namelD, Supported On: 

const IResourceId& iconld); PM. Motif 

Construct an IContainerObject object by providing resource IDs for both the text and 
the icon. 

@ IContainerObject( const IContainerObject& object); Supported On: 

PM. Motif 

Construct an IContainerObject object by copying an existing IContainerObject or a 
class derived from IContainerObject. If you derive from IContainerObject, you 
should provide a copy constructor in the class to ensure that the object is copied 
correctly. 

g IContainerObject( const IString& string. Supported On: 

unsigned long iconld); PM, Motif 

Construct an IContainerObject object by providing an IString for text and an unsigned 
long to use as a resource ID for the icon. 

Note: The User Interface Class Library provides this constructor to resolve a 

potential ambiguity since both IResourcelds and IPointerHandles can be built 
implicitly from an unsigned long integer. 

IContainerObject 


virtual 

'IContainerObjectO; 


Supported On: 

PM, Motif 


Derived Class Provided Members 

These members must be provided by a derived class if the behavior is required. 

handleCursoredChange 

Called when cursored emphasis changes on an object and the IContainerControl (p. 
163) containing the object has an ICnrHandler (p. 95). If the object has just acquired 
cursored emphasis, acquired is set to true. 
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virtual void 

handleCursoredChange( IContainerControl* container. 
Boolean acquired); 


Supported On: 

PM, Motif Ignored 


handlelnuseChange 

Called when in-use emphasis changes on an object and the IContainerControl (p. 163) 
containing the object has an ICnrHandler (p. 95). If the object has just acquired 
in-use emphasis, acquired is set to true. 


virtual void Supported On: 

handleInuseChange( IContainerControl* container, PM, Motif Ignored 

Boolean acquired); 

_Called when the user either selects the Enter key when an object has the cursor or 
double-clicks the mouse select button on an object and the IContainerControl (p. 163) 
containing the object has an ICnrHandler (p. 95). 


virtual void 

handleOpen( IContainerControl* container); 


Supported On: 

PM. Motif 


handleSelectedChange 

Called when selection emphasis changes on an object and the IContainerControl (p. 
163) containing the object has an ICnrHandler (p. 95). If the object has just acquired 
selection emphasis, acquired is set to true. 


virtual void 

handleSelectedChange( IContainerControl* container. 
Boolean acquired); 


Supported On: 

PM. Motif 


handleT reeCollapse 

Called when this object is a parent in the tree view and the descendent objects have 
been collapsed. This is only called when the IContainerControl (p. 163) containing 
the object has an ICnrHandler (p. 95). 


virtual void Supported On: 

handleTreeCollapse( IContainerControl* container); PM, Motif 

handleT reeExpand 

Called when this object is a parent in the tree view and the descendent objects have 
been expanded. This is only called when the IContainerControl (p. 163) containing 
the object has an ICnrHandler (p. 95). 
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virtual void Supported On: 

handleTreeExpand( IContainerControl* container); PM, Motif 

Called when an ICnrHelpEvent (p. 100) is dispatched to ICnrHandler (p. 95). By 
default, this function returns 0. If the ID returned is greater than 0, the default 
behavior of the container's help handler is to display the help panel. 

You can override this function in your classes that inherit from IContainerObject to 
provide the ID of a help panel to display when help is requested for this object. 


virtual unsigned long Supported On: 

helpld() const; PM, Motif 

_Called when it is necessary to make a copy of an object. This occurs when you call 
IContainerControl::copyObjectTo (p. 187). 


virtual IContainerObject* Supported On: 

objectCopy (); PM, Motif 

_.If the objects are at the same storage location, true is returned. 


Boolean 

operator ==( const IContainerObject& object); 


Supported On: 

PM, Motif 


Object Allocation 

These members provide all object allocation and deallocation for instances of the class. Stack 
and static instances of this class are not allowed. 

— Deallocates the storage of a class object. 


Q void 

operator delete( void*); 


Supported On: 

PM, Motif 


S 


void 

operator delete( 


void*, 

const char* fileName, 
size_t lineNumber); 


—Allocates storage for an object of this class. 


Supported On: 

PM, Motif 


| void* 

operator new( size_t size, 

ICnrAl1ocator& allocator); 


Supported On: 

PM 


© IBM Corp. 1992, 1995 


IContainerObject 245 



IContainerObject 


2 void* 

operator new( size_t size, 

const char* fileName, 
size_t lineNumber); 


Supported On: 

PM, Motif 


0 void* Supported On: 

operator new( size_t size, PM 

const char* fileName, 
size_t lineNumber, 

ICnrAl1ocator& allocator); 


Q void* 

operator new( size_t size); 


Supported On: 

PM, Motif 


Object Information 

Use these members to get and set the accessible attributes of this class. 

Note: Because an object can exist in more than one container, many of these functions accept a 
container as an optional parameter. If the container is not specified, the function is 
applied to all containers that this object is in. 


disableDataUpdate 

Disables user updates of this object. 


virtual IContainerObject& Supported On: 

disableDataUpdate( IContainerControl* container = 0); PM, Motif Ignored 

-.Prevents any object from being dropped on this object. 


virtual IContainerObject& 
disableDrop( IContainerControl* container = 0); 


Supported On: 

PM, Motif Ignored 


enableDataUpdate 

Enables user updates of this object if the container in which this object resides is 
enabled for direct editing. 


virtual IContainerObject& 
enableDataUpdate( Boolean enable = true, 

IContainerControl* container = 0); 

—Allows other objects to be dropped on this object. 


Supported On: 

PM, Motif Ignored 
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virtual IContainerObject& 
enableDrop( Boolean enable = true, 

IContainerControl* container = 0); 

.Makes this object invisible by filtering it out. 


Supported On: 

PM. Motif Ignored 


virtual IContainerObject& Supported On: 

hide( IContai nerControl * container = 0); PM. Motif 

Returns the icon handle of an object. If this object does not have an icon, the icon 
handle is zero. 


virtual IPointerHandle 
icon() const; 

Returns the text of an object. 


Supported On: 

PM, Motif 


virtual IString 
iconText() const; 


Supported On: 

PM, Motif 


isDropOnAble 

If this object can accept a drop, true is returned. If container is 0 and this object is 
shared amongst multiple containers, this function returns true only if the object can be 
dropped-on in all of the containers. If you specify a container, this function only 
queries this object's state in the specified container. 


virtual Boolean Supported On: 

isDropOnAble( IContai nerControl * container = 0) const; PM. Motif Ignored 

..If this object has in-use emphasis, true is returned. If container is 0 and this object 
is shared amongst multiple containers, this function returns true only if the object is in 
use in all of the containers. If you specify a container, this function only queries this 
object's state in the specified container. 


virtual Boolean Supported On: 

isInUse( IContai nerControl * container = 0) const; PM. Motif Ignored 

If this object is open, tme is returned. 


virtual Boolean 
is0pen() const; 

__If this object is in a refreshable state, true is returned. 


Supported On: 

PM, Motif 
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virtual Boolean Supported On: 

isRefreshOn() const; PM, Motif Ignored 

If this object is visible, true is returned. If container is 0 and this object is shared 
amongst multiple containers, this function returns true only if the object is visible in 
all of the containers. If you specify a container, this function only queries this 
object's state in the specified container. 

virtual Boolean 

isVisible( IContainerControl* container = 0) const; 

-Returns true if the data in the object can be edited. 

virtual Boolean Supported On: 

isWriteable( IContai nerControl * container = 0) const; PM, Motif Ignored 

Refreshes this object. The object's and container's refresh state must be set to on for 
this function to be valid. You can call IContainerObject::setRefreshOn (p. 249) to do 
so. 

If immediate is set to true, the painting is done synchronously, that is all container 
painting is completed before this function returns to the caller. If immediate is false, 
the container painting will occur asynchronously and painting may not be completed 
when the function returns to the caller. 


Supported On: 

PM, Motif 


virtual IContainerObject& 
refresh( IContainerControl* container = 0, 
Boolean immediate = false); 

—Removes the in-use emphasis for this object. 


Supported On: 

PM, Motif Ignored 


virtual IContainerObject& Supported On: 

removelnUsej IContai nerControl * container = 0); PM, Motif Ignored 

.Removes the open emphasis in all containers. 


virtual IContainerObject& 
setClosed(); 

..Sets a new icon for an object. 


Supported On: 

PM, Motif 


0 virtual IContainerObject& 

setlconj const IPointerHandle& iconHandle); 


Supported On: 

PM, Motif 


248 Open Class Library Reference 



IContainerObject 


g virtual IContainerObject& 

set!con( const IResourceId& iconld); 


£j virtual IContainerObject& 

setIcon( unsigned long iconld); 

_ Sets the new text for an object. 

| virtual IContainerObject& 

setIconText( const IString& iconText); 


§ virtual IContainerObject& 

setIconText( const char* iconText); 


£j virtual IContainerObject& 

setIconText( const IResourceId& iconTextld); 

...Sets the in-use emphasis for this object. 


virtual IContainerObject& 

setInUse( Boolean inllse = true, 

IContainerControl* container = 0); 

_Sets the open emphasis. 


virtual IContainerObject& 

setOpen( Boolean open = true); 


setRefreshOff 

Prevents refreshing of this object. 


virtual IContainerObject& 
setRefreshOff(); 


setRefreshOn 

Allows refreshing of this object. 


virtual IContainerObject& 

setRefreshOn( Boolean refreshOn = true); 

Makes this object visible. 
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Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM, Motif 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM. Motif Ignored 
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virtual IContainerObject& 
show( Boolean show = true, 

IContainerControl* container = 0); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Attributes 

These members implement the class. 

- Returns the address of the real base of this object. 


IMiniCnrRecord* 
baseRecord(); 


Supported On: 

PM, Motif 


decrementUseCount 

Decreases the count of containers having this object. 


virtual IContainerObject& Supported On: 

decrementUseCount (); PM, Motif 

incrementUseCount 

Increases the count of containers having this object. 


virtual IContainerObject& 
incrementUseCount(); 

..Initializes an object after construction. 


Supported On: 

PM, Motif 
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virtual IContainerObject& 
initial ize(); 

_If the specified attribute is set to on, true is returned. 


Supported On: 

PM, Motif 


virtual Boolean 

isAttribute( unsigned long attribute, 

IContainerControl* container) const; 


Supported On: 

PM, Motif 


_Sets some attributes to off while setting others to on. Use this function to toggle 
the state of mutually exclusive attributes. If you do not specify a container, the 
changes are made to all containers that have this object. 


virtual IContainerObject& 

setAttributes( unsigned long attributeTurnedOff, 
unsigned long attributeTurnedOn, 
IContainerControl* container = 0); 

.Stores the address of the real base of this object. 


Supported On: 

PM, Motif 


virtual IContainerObject& Supported On: 

setBase( const IMiniCnrRecord* baseRecord); PM, Motif 

_Sets the specified emphasis attribute to on or off. If you do not specify a container, 
the changes are made to all containers that have this object. 


virtual IContainerObject& 

setEmphasis( unsigned long emphasisAttribute. 
Boolean turnOn = true, 
IContainerControl* container = 0); 

.Returns the number of containers having this object. 


Supported On: 

PM, Motif 


unsigned long 
useCount() const; 


Supported On: 

PM, Motif 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Emphasis { 
none = 0, 
cursored = 1, 
inuse = 2, 
selected = 4 
}; 


These enumerators specify a visible indication of the condition of an object affecting 
the ability of a user to interact with that object: 

none 

Provides no emphasis. Use this enumerator when no emphasis is required. 

cursored 

Provides a visible indication that the object contains the cursor. 

inuse 

Provides a visible indication that an object has been opened. 

selected 

Provides a visible indication that an object has been selected by the user. 
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ICustomButton 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

ICustomButton 


I AnimatedB utton 
IToolBarButton 


_.icustbut.hpp 


Member Page 

Constructor 255 

autoLatch 261 

backgroundColor 254 

calcMinimumSize 260 

classDefaultStyle 261 

convertToGUIStyle 257 

defaultStyle 258 

disable AutoLatch 256 

disableLatching 256 

enable AutoLatch 256 

enableLatching 256 

isAutoLatchEnabled 256 

isLatched 257 

isLatchedBackgroundColorHalftone 254 

isLatchingEnabled 257 


Member 

Page 

latch 

257 

latchable 

261 

1 atchedB ackgroundColor 

254 

latchedForegroundColor 

254 

latchld 

260 

resetLatchedB ackgroundColor 

254 

resetLatchedForegroundColor 

255 

setDefaultStyle 

258 

setLatchedB ackgroundColor 

255 

setLatchedForegroundColor 

255 

setUserData 

258 

unlatch 

257 

userData 

258 

“ICustomButton 

256 


The ICustomButton class creates and manages the custom button window. Custom 
buttons allow the application to customize the button appearance by providing an 
ICustomButtonDrawHandler to draw the button. 
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Public Functions 
Colors 

Use these members to set or query the color attributes of a custom button. 


backgroundColor 

Returns the color used to paint the background of the custom button when it is in the 
default state. 

virtual IColor 
backgrounded or () const; 

isLatchedBackgroundColorHalftone 

Returns true if the background is a halftone when the custom button is in the latched 
state. 

virtual Boolean Supported On: 

i sLatchedBackgroundCol orHal ftone() const; PM 

latched BackgroundColor 

Returns the color used to paint the background of the custom button when it is in the 
latched state. 

virtual IColor 

1atchedBackgroundColor() const; 

latchedForegroundColor 

Returns the color used to paint the foreground of the custom button when it is in the 
latched state. 


Supported On: 

PM 


Supported On: 

PM 


virtual IColor 

1atchedForegroundColor() const; 


Supported On: 

PM 


resetLatchedBackgroundColor 

Resets the latched background color by undoing a previous set. 


virtual ICustomButton& 
resetLatchedBackgroundColor(); 


Supported On: 

PM 
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resetLatchedForegroundColor 

Resets the latched foreground color by undoing a previous set. 


virtual ICustomButton& 

resetLatchedForegroundColor(); 


Supported On: 

PM 


setLatchedBackgroundColor 

Sets the color used to paint the background of the button when it is in the latched 
state. 


virtual ICustomButton& 

setLatchedBackgroundColor( const IColor& color. 

Boolean halftone = true); 


Supported On: 

PM 


setLatchedForegroundColor 

Sets the color used to paint the foreground of the button when it is in the latched 
state. 


virtual ICustomButton& 

setLatchedForegroundColor( const IColor& color); 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign ICustomButton 
objects because both the copy constructor and assignment operator are private functions. 

ICustomButton 

| ICustomButton( unsigned long id, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Creates an ICustomButton with the specified window ID, parent and owner windows, 
screen position and size, and window style. 

Exceptions 

IlnvalidParameter The parent window pointer is invalid. 


£ ICustomButton( const IWindowHandle& handle); Supported On: 

PM 


Supported On: 

PM 
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Creates an ICustomButton object for the specified button control that has a 
user-button style. 

ICustomButton 

virtual Supported On: 

"ICustomButton(); PM 


Latch Support 

Use these members to manage the latched state of a custom button. 


disableAutoLatch 

Disables the autoLatch style. 


virtual ICustomButton& 
disableAutoLatch(); 


Supported On: 

PM 


disableLatching 

Sets the style of the button so that the user cannot latch or unlatch it. 


virtual ICustomButton& 
disableLatching (); 


Supported On: 

PM 


enableAutoLatch 

Sets the style of the button so that other custom buttons in the same group that have 
the autoLatch style are automatically unlatched when the user latches the button. 


virtual ICustomButton& 
enableAutoLatch( Boolean enable = true); 


Supported On: 

PM 


enableLatching 

Sets the style of the button so that the user can latch or unlatch it. 

Supported On: 

PM 

isAutoLatchEnabled 

Returns true if the autoLatch style is set for the button. 


virtual ICustomButton& 
enableLatching( Boolean enable = true); 
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virtual Boolean 

isAutoLatchEnabled() const; 

Supported On: 

PM 

-.Returns true if the button is in a latched state. 


virtual Boolean 
isLatched() const; 

Supported On: 

PM 

isLatchingEnabled 

Returns true if the latchable style is set for the button. 


virtual Boolean 

isLatchingEnabled() const; 

Supported On: 

PM 

Puts the button in a latched state. 


virtual ICustomButton& 

latch( Boolean latched = true, 

Boolean refresh = true); 

Supported On: 

PM 

Puts the button in the unlatched (default) state. 


virtual ICustomButton& 
unlatch(); 

Supported On: 

PM 

Styles 

Use these members to set and query ICustomButton styles. You can use 
styles defined by the following nested classes: 

these styles with the 

IWindow Styles (Vol. II) 

IControl Styles (Vol. II) 

IButton Styles (Vol. II) 


If the latchable style is set for the button but not the autoLatch style, then the user can latch and 
unlatch the button directly. If the autoLatch style is set for the button but not the latchable style, 
then the user can latch the button but cannot unlatch it directly. The user must latch another 
custom button that has the autoLatch style to unlatch the previous button. If both the latchable 
and autoLatch styles are set for the button, then the user can latch and unlatch the button 
directly. Also, the button automatically unlatches itself when the user latches another custom 
button that has the autoLatch style. 

convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 
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Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFI ag& style, PM 

Boolean extendedOnly = false) const; 

—Returns the default style. The default style is classDefaultStyle unless you have 
changed the style using setDefaultStyle. 

static Style Supported On: 

defaultStyle(); PM 


setDefaultStyle 

Sets the default style for all subsequent custom buttons. 

style Use the styles provided by ICustomButton::Styles to specify the default 

style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM 


User Data 

Use these members to set or query user data for custom button objects. 

— Stores an unsigned long value that represents special data to be associated with the 
button object. 

ICustomButton& Supported On: 

setUserData( unsigned long data); PM 

-Returns an unsigned long value that represents special data associated with the 
button object. This data can be used to store information about special drawing for 
the button. 

unsigned long Supported On: 

userData() const; PM 


Inherited Public Functions 
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IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableNotification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign ICustomButton 
objects because both the copy constructor and assignment operator are private functions. 


ICustomButton 


ICustomButtonO; 


Supported On: 

PM 
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ICustomButton 


Layout Support 

These members provide layout support for custom buttons. 

calcMinimumSize 

Returns the recommended minimum size of this custom button control. The size is 
based on button text and the current font. 

virtual ISize Supported On: 

calcMinimumSize() const; PM 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 


Notification Members 

These INotificationld strings are used for all notifications that ICustomButton provides to its 
observers. 

This notification identifier is provided to observers when the user latches or 
unlatches the button. A Boolean value is provided in the 

INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is true if the button is currently in the latched state. 


static INotificationld const 
latchld; 


Supported On: 

PM 


Styles 

Use these members to set and query ICustomButton styles. You can use these styles with the 
styles defined by the following nested classes: 

IWindow Styles (Vol. II) 

IControl Styles (Vol. II) 

IButton Styles (Vol. II) 
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If the latchable style is set for the button but not the autoLatch style, then the user can latch and 
unlatch the button directly. If the autoLatch style is set for the button but not the latchable style, 
then the user can latch the button but cannot unlatch it directly. The user must latch another 
custom button that has the autoLatch style to unlatch the previous button. If both the latchable 
and autoLatch styles are set for the button, then the user can latch and unlatch the button 
directly. Also, the button automatically unlatches itself when the user latches another custom 
button that has the autoLatch style. 

-Unlatches automatically other custom buttons in the same group when the user 
latches button. This style also allows the user to latch the button when clicking on 
the button with mouse button 1. 

static const Style Supported On: 

autoLatch; PM 

classDefaultStyle 

Specifies the original default style for this class, which is IWindow::visible. 

static const Style Supported On: 

classDefaultStyle; PM 

-Allows the user to latch or unlatch the custom button when clicking on the button 
with mouse button 1. 


static const Style 
1atchable; 


Supported On: 

PM 
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IWindow 

activeColorld 

disabiedBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

ICustomButton contains the following nested classes: 
ICustomButton::Style (see page 263) 


262 
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ICustomButton: :Style 



ICustomButton::Style 


IBase 

IBitFlag 

ICustomButton: :Style 


_.None. 

_icustbut.hpp 

The nested class ICustomButton::Style provides a set of valid styles for the static 
member functions of the class ICustomButton. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICustomButtonDrawEvent 



ICustomButtonDrawEvent 


IBase 

IVBase 

IEvent 

IControlEvent 
ICustomB uttonDrawEvent 


_.None. 


—icustbev.hpp 

Member 

Page 

Constructor 

264 

buttonState 

265 

customButton 

265 

drawDown 

265 

drawingArea 

265 

drawLatched 

265 


Member 

Page 

drawUp 

265 

graphicContext 

266 

isButtonEnabled 

266 

setDrawingArea 

266 

'ICustomButtonDrawEvent 

265 


The ICustomButtonDrawEvent class provides information about a custom button 
event for ICustomButtonDrawHandler event handling functions. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot assign 
ICustomButtonDrawEvent objects because the assignment operator is a private function. 


ICustomButtonDrawEvent 

| ICustomButtonDrawEvent( const IEvent& event); 

Creates an ICustomButtonDrawEvent from the specified IEvent. 

2 ICustomButtonDrawEvent( 

const ICustomButtonDrawEvent& event); 


Supported On: 

PM 


Supported On: 

PM 
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Creates an ICustomButtonDrawEvent from the specified ICustomButtonDrawEvent. 

ICustomButtonDrawEvent 


virtual 

"ICustomButtonDrawEventO; 


Supported On: 

PM 


Custom Button 

Use these members to query information about the custom button. 


customButton 

Returns a pointer to the ICustomButton object that is to be drawn. 


virtual ICustomButton* 
customButton() const; 


Supported On: 

PM 


Drawing 

Use these members to query or modify the event-drawing information. 

- Returns the state that describes how the button is to be drawn. 


ButtonState Supported On: 

buttonState() const; PM 

Returns true if the button is to be drawn in the down state. 


Boolean Supported On: 

drawDown() const; PM 

—Returns the current drawing area rectangle to be used when drawing the button. 


IRectangle Supported On: 

drawingArea() const; PM 

—Returns true if the button is to be drawn in the latched state. 


Boolean Supported On: 

drawLatched() const; PM 

Returns true if the button is to be drawn in the up state. 
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ICustomButtonDrawEvent 


Boolean 

drawlipO const; 


Supported On: 

PM 


graphicContext 

Returns a graphic context to be used when drawing the button. 

IGraphicContext& Supported On: 

graphicContext() const; PM 


isButtonEnabled 

Returns true if the button is to be drawn in the enabled state. 


Boolean 

isButtonEnabled() const; 


Supported On: 

PM 


setDrawingArea 

Sets the current drawing area rectangle to be used when drawing the button. 


virtual ICustomButtonDrawEvent& 
setDrawingArea( const IRectangle& rectangle); 


Supported On: 

PM 


Inherited Public Functions 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 
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ICustomButtonDrawEvent 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



ButtonState { 
buttonllp, 
buttonDown, 
buttonLatched 
}; 


Enumeration used to describe the state to be used to draw the button: 

buttonUp 

The button is to be drawn in the up state. 

buttonDown 

The button is to be drawn in the down state. 

buttonLatched 

The button is to be drawn in the latched state. 
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ICustomButtonDrawHandler 


IBase 

IVBase 

IHandler 

ICustomB uttonDrawHandler 


_.None. 


_icustbhd.hpp 


Member 

Page 

Member 

Page 

Constructor 

268 

drawB utton 

270 

dispatchHandlerEvent 

269 

drawDisabledEmphasis 

270 

drawB ackground 

269 

drawForeground 

270 

drawB order 

270 

'ICustomButtonDrawHandler 

268 


The ICustomButtonDrawHandler class is processes ICustomButton drawing events. 

Note: Attach objects of this class only to ICustomButton objects. Attaching an 

ICustomButtonDrawHandler to the owner of an ICustomButton will not work 
correctly. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ICustomButtonDrawHandler 


ICustomButtonDrawHandler(); 


Supported On: 

PM 


The only way to construct objects of this class is with the default constructor. 

'ICustomButtonDrawHandler 
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ICustomButtonDrawHandler 


virtual 

'ICustomButtonDrawHandler(); 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 


dispatchHandlerEvent 

Calls the appropriate virtual function or functions to process a custom button draw 
event. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM 


Event Processing 

Event-processing members provide information about handling events. 

drawBackground 

Called to draw the background of the button. You can override this function to 
change the way the button's background is drawn. 
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ICustomButtonDrawHandler 


The default behavior is to fill the current drawing area with the background color or 
latched background color. 

virtual void Supported On: 

drawBackground( ICustomButtonDrawEvent& event); PM 

_.Called to draw the border of the button. The default implementation draws the 
border and removes the area painted from the button drawing area. Uses the margin 
option to specify the amount of white space that to be left around the button. You 
can override this function to change the way the button border is drawn. 

Note: If the button's drawing area rectangle is not reduced (by removing the area 
occupied by the border), then the background and foreground of the button 
can paint over the border. 

virtual void Supported On: 

drawBorder( ICustomButtonDrawEvent& event, PM 

ISize margin = ISize ( )); 

- Called when the button needs to be redrawn on the screen. This can occur when 
the button has just become visible or if the state of the button has changed. 

You can override this function to change the way the button is displayed on the 
screen. The default implementation calls the functions drawBorder, drawBackground, 
drawForeground, and (if disabled) drawDisabledEmphasis, and then returns true. 

virtual Boolean Supported On: 

drawButton( ICustomButtonDrawEvent& event); PM 

drawDisabledEmphasis 

Called to draw disabled emphasis for the button. You can override this function to 
change the way the button's disabled emphasis is drawn. 

The default behavior is to use a halftone in the current drawing area. 

virtual void Supported On: 

drawDi sabl edEmphasi s ( ICustomButtonDrawEvent& event); PM 


drawForeground 

Called to draw the foreground of the button. You can override this function to 
change the way the button's foreground is drawn. 

The default behavior is to draw the custom button text with the foreground or latched 
foreground color. 
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virtual void Supported On: 

drawForeground( ICustomButtonDrawEvent& event); PM 


Inherited Protected Functions 



Inherited Protected Data 
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IDDE 



IDDE 


IBase 

IDDE 


_.None. 

_iddecomm.hpp 


Member Page 

bitmapFormat 272 

codepageTextFormat 273 

dibFormat 273 

difFormat 273 

displayBitmapFormat 273 

displayMetafileFormat 273 

displayMetafilePictureFormat 273 

displayTextFormat 274 


Member 

Page 

linkFormat 

274 

metafileFormat 

274 

metafilePictureFormat 

274 

oemTextFormat 

274 

paletteFormat 

274 

sylkFormat 

275 

textFormat 

275 

tiffFormat 

275 


This class contains synonyms for DDE formats that are pre-defined by the operating 
system. 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 

DDE Text Formats 

Dynamic Data Exchange formats that the class library supports. 


bitmapFormat 

The layout of this format is a BITMAPINF02 structure. 
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IDDE 


static Format const Supported On: 

bi tmapFormat; PM 

codepageTextFormat 

This format consists of a CPTEXT structure, where the text portion of the structure 
must be in IDDE::textFormat format. The format allows applications to exchange 
text in a particular codepage. 

static Format const Supported On: 

codepageTextFormat; PM 

...This format consists of a DIB structure. 


static Format const Supported On: 

dibFormat; PM 

.This format represents the Data Interchange Format which was developed by 

Software Arts and is used to transfer data to a Visicalc spreadsheet program. 


static Format const 
difFormat; 


Supported On: 

PM 


displayBitmapFormat 

The layout of this format is identical to that of the IDDE::bitmapFormat format. This 
format is the bitmap representation of a private data format. 

static Format const Supported On: 

displayBitmapFormat; PM 


displayMetafileFormat 

The layout of this format is identical to that of the IDDE::metafileFormat format. 

This format is the metafile representation of a private data format. 

static Format const 
displayMetafi1eFormat; 

displayMetafilePictureFormat 

The layout of this format is identical to that of the IDDE::metafilePictureFormat 
format. This format is the metafile picture representation of a private data format. 

static Format const Supported On: 

di spl ayMetafi 1 ePi ctureFormat; PM 


Supported On: 

PM 
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IDDE 


displayTextFormat 

The layout of this format is identical to that of the textFormat format. It is the 
textual format of a private data format. 

static Format const Supported On: 

displayTextFormat; PM 

.This format contains information needed to establish a DDE hot link. It is typically 

used in paste-link operations where the clipboard is being used to exchange 

information. The layout of the link format is: 

applic ationN ame(0x00)topicN ame(0x00)itemN ame (0x00) (0x00). 

static Format const Supported On: 

linkFormat; PM 


metafileFormat 

This format contains the bits retrieved via the GpiQueryMetafileBits function. 

static Format const Supported On: 

metafileFormat; PM 

metafilePictureFormat 

This layout of this format consists of an MFP structure. It includes the information 
provided in the IDDE: metafileFormat format, with additional information defining 
the metafile bits. 

static Format const Supported On: 

metafilePictureFormat; PM 


oemTextFormat 

The layout of this format is identical to that of the IDDE::textFormat format. This 
format indicates that the text has been created using codpage 437 which is the 
U.S.-ENGLISH codepage. 

static Format const Supported On: 

oemTextFormat; PM 


paletteFormat 

This format consists of a PALETTEINFO structure. 


274 Open Class Library Reference 



IDDE 


static Format const Supported On: 

paletteFormat; PM 

..This format represents the Symbolic Link format developed by Microsoft Corp., 
which is used to exchange spreadsheets in an ASCI text format. 

static Format const Supported On: 

sylkFormat; PM 

.This is a NULL (0x00) terminated ANSI character string. The string can contain a 

carriage return (OxOD) and/or a line-feed character (OxOA) to mark the end of a line. 


static Format const Supported On: 

textFormat; PM 

.This format represents the Tag Image File Format which was developed by 

Microsoft, Aldus, and Hewlett-Packard for describing bitmapped data. 


static Format const Supported On: 


tiffFormat; 


PM 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 



Nested Type Definitions 

typedef const char * Format; 

This is a synonym for the pre-defined DDE formats. 
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IDDEAcknowledgeEvent 


IBase 

IVBase 

IEvent 

IDDEEvent 

IDDEAcknowledgeEvent 


IDDEAcknowledgeExecuteEvent 

IDDEAcknowledgePokeEvent 


IDDEClientAcknowledgeEvent 

IDDEServerAcknowledgeEvent 


—iddeevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

277 

isMessageUnderstood 

111 

applicationSpecificData 

277 

transactionType 

278 

isAckPositive 

111 

'IDDEAcknowledgeEvent 

111 

isApplicationBusy 

111 




The IDDEAcknowledgeEvent class is the base class for the Dynamic Data Exchange 
(DDE) acknowledge event information classes. 

An object of this class or one of its subclasses is created when an 
IDDEClientConversation object or IDDETopicServer object needs to pass 
acknowledgment information to the client or server application. You do not construct 
objects of this class. See IDDEClientConversation (p. 297) and IDDETopicServer (p. 
346) for information about those classes. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDETopicServer or 
IDDEClientConversation objects. 
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IDDEAcknowledgeEvent 

IDDEAcknowledgeEvent( const IEvent& ddeEvent); Supported On: 

PM 


IDDEAcknowledgeEvent 

"IDDEAcknowledgeEventO ; Supported On: 

PM 


Event Information 

Use these members to query information about an acknowledgment. 

appiicationSpecificData 

Returns any application-specific data that has been provided by the conversing 
application. 

unsigned char Supported On: 

applicationSpecificData() const; PM 


isAckPositive 

Returns true if the acknowledgment is positive; otherwise, it returns false. 

Boolean Supported On: 

isAckPositive() const; PM 

isApplicationBusy 

Returns true if the application busy flag is on; otherwise, it returns false. This is only 
set for a negative acknowledgment. 

Boolean 

isApplicationBusy() const; 

isMessagellnderstood 

Returns false if the message not understood flag is on; otherwise, it returns true. This 
is only set for a negative acknowledgment. 

Boolean Supported On: 

isMessagellnderstood() const; PM 


Supported On: 

PM 
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IDDEAcknowledgeEvent 


Inherited Public Functions 


IDDEEvent 

format 

item 



IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Information 

Use these members to query information about an acknowledgment. 


transactionType 

Returns the event ID. 

unsigned short Supported On: 

transactionType() const; PM 


Inherited Protected Functions 
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IDDEAcknowledgeEvent 


IDDEEvent 

buffer 

setBuffer 

setStatus 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDDEAcknowledgeExecuteEvent 


IBase 

IVBase 

IEvent 

IDDEEvent 

IDDEAcknowledgeEvent 

IDDEAcknowledgeExecuteEvent 


_.None. 

__iddeevt.hpp 


Member Page 

Constructor 280 

commands 281 

“IDDEAcknowledgeExecuteEvent 281 


The IDDEAcknowledgeExecuteEvent class provides event information to a client 
application regarding an acknowledgment of an executeCommands request. 

An object of this class is created when an IDDEClientConversation object needs to 
pass information to the client application about an acknowledgment resulting from an 
IDDEClientConversation: :executeCommands request. You do not construct objects of 
this class. See IDDEClientConversation (p. 297) and executeCommands (p. 303) for 
information about that class and function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDEClientConversation objects. 


IDDEAcknowledgeExecuteEvent 

IDDEAcknowledgeExecuteEvent const IEvent& ddeEvent); Supported On: 

PM 
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IDDEAcknowledgeExecuteEvent 

"IDDEAcknowledgeExecuteEvent (); Supported On: 

PM 


Event Information 

Use these members to query information about the command string you sent to the DDE server 
application. 

-. Returns the command string that the client asked the server application to execute. 

Note: The !DDEAcknowledgeExecuteEvent::commands function's IString is 
constructed from a void* and length. For character strings, if the terminating NULL 
is included in the length, it is in the buffer. Before performing string operations such 
as concatenation on this string, use IString: :stripTrailing to strip any trailing NULL 
character. 

See IString (Vol. I) and stripTrailing (Vol. I) for information about that class and 
function. 

IString Supported On: 

commands() const; PM 


Inherited Public Functions 


IDDEAcknowledgeEvent 

applicationSpecificData 

isAckPositive 

isApplicationBusy 


IDDEEvent 

format 

item 



IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 
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IDDEAcknowledgeExecuteEvent 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDDEAcknowledgeEvent 

transactionType 




IDDEEvent 

buffer 

setBuffer 

setStatus 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDDEAcknowledgePokeEvent 


IBase 

IVBase 

IEvent 

IDDEEvent 

IDDEAcknowledgeEvent 

IDDEAcknowledgePokeEvent 


_.None. 

__iddeevt.hpp 


Member Page 

Constructor 283 

pokedData 284 

'IDDEAcknowledgePokeEvent 284 


The IDDEAcknowledgePokeEvent class provides event information to a client 
application regarding an acknowledgment to a !DDEClientConversation::pokeData 
request. 

An object of this class is created when an IDDEClientConversation object needs to 
pass information to the client application about an acknowledgment resulting from a 
pokeData request. You do not construct objects of this class. See 
IDDEClientConversation (p. 297) and pokeData (p. 304) for information about that 
class and function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDEClientConversation objects. 


IDDEAcknowledgePokeEvent 

IDDEAcknowledgePokeEvent( const IEvent& ddeEvent) ; Supported On: 

PM 
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IDDEAcknowledgePokeEvent 


IDDEAcknowledgePokeEvent 

"IDDEAcknowledgePokeEvent(); Supported On: 

PM 


Event Information 

Use these members to query information about the data you sent to the DDE server application. 

_ Returns the data that the client asked the server application to set. 

Note: The IDDEAcknowledgePokeEvent::pokedData function's IString is constructed 
from a void* and length. For character strings, if the terminating NULL is included 
in the length, it is in the buffer. Before performing string operations such as 
concatenation on this string, use IString::stripTrailing to strip any trailing NULL 
character. 

See IString (Vol. I) and stripTrailing (Vol. I) for information about that class and 
function. 

IString Supported On: 

pokedData() const; PM 


Inherited Public Functions 


IDDEAcknowledgeEvent 

applicationSpecificData 

isAckPositive 

isApplicationBusy 


IDDEEvent 

format 

item 



IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 
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IDDEAcknowledgePokeEvent 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDDEAcknowledgeEvent 

transactionType 




IDDEEvent 

buffer 

setBuffer 

setStatus 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 
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IDDEActiveServer 


IBase 

IDDEActiveServer 


_.None. 


_iddecset.hpp 


Member 

Page 

Member 

Page 

Constructor 

286 

topic 

287 

application 

287 

'IDDEActiveServer 

287 

isCaseSensitive 

287 




The IDDEActiveServer class holds information about a Dynamic Data Exchange 
(DDE) server application and a particular topic the server application supports. 

Objects of this class are created to provide information about possible conversations 
when one of the two broadcast functions, !DDEClientConversation::supportedTopics 
or IDDEClientConversation::supportingApplications, is called. 

IDDEClientConversation objects create objects of this class, which are not intended to 
be created by application programmers. See IDDEClientConversation (p. 297), 
supportedTopics (p. 298), or supportingApplications (p. 298) for more information. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDEClientConversation objects. 


IDDEActiveServer 

IDDEActiveServer( const char* appl icationName, Supported On: 

const char* topicName, PM 

Boolean caseSensitive); 
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IDDEActiveServer 


TDDEActiveServer 

"IDDEActiveServer(); 


Supported On: 

PM 


Server Attributes 

Use these members to query information about a DDE server application. 

_ Returns the name of the server application. 

IString Supported On: 

application() const; PM 


isCaseSensitive 

Returns true if the server enforces case sensitivity; otherwise, it returns false. 

Boolean Supported On: 

isCaseSensitive() const; PM 

Returns the name of the topic supported by the server. 


IString Supported On: 

topicQ const; PM 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDDEActiveServerSet 


ISet 

IDDEActiveServerSet 


_.None. 


_iddecset.hpp 


Page 

288 

289 


Member 

Constructor 

'IDDEActiveServerSet 


The IDDEActiverServerSet class is a set created using the ISet template class. The 
set contains pointers to IDDEActiveServer objects. See IDDEActiveServer (p. 286) 
for information about that class. 

An application creates an object of this class to use with the 
IDDEClientConversation: :supportingApplications or 

IDDEClientConversation::supportedTopics function to hold the current set of active 
servers. If you remove individual elements of this set, delete the IDDEActiveServer 
object to which the element points or the memory is not recovered. See 
supportingApplications (p. 298) and supportedTopics (p. 298) for information about 
those functions. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IDDEActiveServerSet 

IDDEActiveServerSetQ; Supported On: 

PM 

You can construct an object of this class using the default constructor, which does not 
accept any arguments. 
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TDDEActiveServerSet 

This function removes all the elements from the set, and deletes them. 


"IDDEActiveServerSet (); 


Supported On: 

PM 
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IDDEBeginEvent 


IBase 

IVBase 

IEvent 

IDDEBeginEvent 


_.None. 


_iddeevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

290 

topic 

291 

application 

291 

'IDDEBeginEvent 

291 

setCaseSensitive 

291 




The IDDEBeginEvent class provides event information to a server application when a 
client has asked the server to begin a conversation. 

An object of this class is created when an IDDETopicServer object needs to pass an 
acceptConversation request to the server application. You do not construct objects of 
this class. See IDDETopicServer (p. 346) and acceptConversation (p. 353) for 
information about that class and function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDETopicServer objects. 


IDDEBeginEvent 

IDDEBeginEvent( const IEventS ddeBeginEvent); Supported On: 

PM 
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"IDDEBeginEvent 

"IDDEBeginEvent (); 


Supported On: 

PM 


Event Attributes 

Use these members to query information about the requested conversation and to set 
the case sensitivity of the conversation, if it is accepted. 

_ Returns the name of the requested application. 

IString 

application() const; 

setCaseSensitive 

Sets the case-sensitive flag to true. The server application should set this flag if it 
enforces case sensitivity. 

IDDEBeginEvent& 

setCaseSensitive( Boolean caseSensitive); 

Returns the name of the requested topic. 

IString Supported On: 

topic() const; PM 


Supported On: 

PM 


Supported On: 

PM 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDDEClientAcknowledgeEvent 


IBase 

IVBase 

IEvent 

IDDEEvent 

IDDEAcknowledgeEvent 

IDDEClientAcknowledgeEvent 


_.None. 
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The IDDEClientAcknowledgeEvent class provides event information to a client 
application regarding an acknowledgment from a server. 

An object of this class or one of its subclasses is created when an 
IDDEClientConversation object needs to pass information about an acknowledgment 
to the client application. You do not construct objects of this class. See 
IDDEClientConversation (p. 297) for information about that class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDEClientConversation objects. 


IDDEClientAcknowledgeEvent 

IDDEClientAcknowledgeEvent) const IEvent& ddeEvent); Supported On: 

PM 
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"IDDEClientAcknowledgeEvent 

'IDDEClientAcknowledgeEvent(); Supported On: 

PM 


Event Information 

Use these members to query information about the type of the event that the acknowledgment is 
for. 

isAckToBeginHotLink 

Returns true if the acknowledgment is in response to 

lDDEClientConversation::beginHotLink being called; otherwise, it returns false. 

See beginHotLink (p. 302) for information about that member. 

Boolean 

isAckToBeginHotLink() const; 

isAckToEndHotLink 

Returns true if the acknowledgment is in response to 

IDDEClientConversation::endHotLink being called; otherwise, it returns false. 

See endHotLink (p. 303) for information about that member. 

Boolean 

isAckToEndHotLink() const; 

isAckToRequestData 

Returns true if the acknowledgment is in response to 

lDDEClientConversation::requestData being called; otherwise, it returns false. 

See requestData (p. 304) for information about that member. 

Bool ean Supported On: 

isAckToRequestData() const; PM 


Supported On: 

PM 


Supported On: 

PM 
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Inherited Public Functions 


IDDEAcknowledgeEvent 

applicationSpecificData 

isAckPositive 

isApplicationBusy 


IDDEEvent 

format 

item 



IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDDEAcknowledgeEvent 

transactionType 




IDDEEvent 

buffer 

setBuffer 

setStatus 
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IDDEClientConversation 


IBase 

IVBase 

IHandler 

IDDEClientConversation 


_.None. 


_ iddeccnv.hpp 
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end 

301 

pokeAcknowledged 
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endAllHotLinks 

309 

pokeData 

304 

endHotLink 
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requestData 

304 

endHotLinks 
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supportedT opics 
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executeAcknowledged 

308 

supportingApplications 

298 

executeCommands 
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topic 

300 

findTransaction 
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299 
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306 




The IDDEClientConversation class adds Dynamic Data Exchange (DDE) client 
function to an application. 

Create an object of this class for each conversation you want to initiate with a server 
application. The object manages all window, shared memory, and atom table 
processing. When a conversation with a server ends, the IDDEClientConversation 
object can initiate another conversation with that server or any other server. An 
object of this class can find all topics supported by all DDE server applications on the 
system. 

This class uses a window to communicate; therefore, window message processing 
must occur. This means that ICurrentThread::processMsgs must be called. There are 
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several ways for this to occur. Normally, this is accomplished by calling 
IApplication::current().run(). See processMsgs (Vol. II), current (Vol. II), and run 
(Vol. II) for information about those members. 


Public Functions 
Broadcasts 

Use these members to query information about the topics supported by the currently active DDE 
server applications. 


supportedTopics 

Adds IDDEActiveServer objects that represent topics supported by DDE server 
applications to the IDDEActiveServerSet passed in as the first argument. If the 
applicationName argument is specified, only the topics supported by that application 
are added to the set. The default is to add all topics supported by all server 
applications. 

Note: Include the iddecset.hpp header file when you use this function. 

See IDDEActiveServer (p. 286) and IDDEActiveServerSet (p. 288) for information 
about those classes. 

virtual IDDEClientConversation& Supported On: 

supportedTopics( IDDEActiveServerSet& activeServerSet, PM 

const char* applicationName = 0); 


supportingApplications 

Adds IDDEActiveServer objects that represent DDE server applications that support 
the specified topic to the IDDEActiveServerSet passed in as the first argument. 

Note: Include the iddecset.hpp header file when you use this function. 

See IDDEActiveServer (p. 286) and IDDEActiveServerSet (p. 288) for information 
about those classes. 

virtual IDDEClientConversation& Supported On: 

supportingApplications( IDDEActiveServerSet& activeServerSet, PM 

const char* topicName); 

Exceptions 

IlnvalidParameter The topicName parameter is NULL. 
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Constructors 

You can construct objects of this class in two ways. Both constructors have a Boolean argument, 
useEventThread. This argument is optional but is also highly recommended if the application 
must do any extensive processing or interacts with the user during any of the callback functions. 
Specifying true allows IDDEClientConversation to create a secondary thread to process incoming 
events. This prevents problems with window message processing because the thread is created 
without a message queue. If you specify false, no secondary thread is created and you should 
return promptly from all callback functions. 

IDDEClientConversation 

Q 


g IDDEClientConversation( const char* appl icationName, Supported On: 

const char* topicName, PM 

Boolean useEventThread = true); 

This constructor accepts the following arguments and attempts to begin a conversation 
with the requested server application on the requested topic: 

• The name of the server application with which a conversation is desired 

• The name of the topic about which a conversation is desired 
Exceptions 

IOutOfSystemResource The operating system request for either an event semaphore or a queue 
failed. See the text of the exception for further information. 


IDDEClientConversation( Boolean useEventThread = true); Supported On: 

PM 

This constructor initializes the object but does not start a conversation. 

Exceptions 

IOutOfSystemResource The operating system request for either an event semaphore or a queue 
failed. See the text of the exception for further information. 


"IDDEClientConversation 

The destructor ends the conversation with the DDE server application if there is one 
active. 

virtual Supported On: 

'IDDEC1 i entConversation(); PM 
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Conversation Information 

Use these members to obtain the attributes of this object, including information about the 
conversation if there is one currently active. 

.. Returns the name of the server application with which the client is conversing. 

IString Supported On: 

application() const; PM 

- Returns the window handle of the client conversation. This is provided, along with 
the IDDEClientConversation::begin member, to allow an object of this class to 
converse with a server without engaging in the normal conversation initialization. 

See begin (p. 301) for information about that member. 

IWi ndowHandl e Supported On: 

cl ientHandle() const; PM 


inConversation 

Returns true if the client is currently in conversation with a server; otherwise, it 
returns false. 

Bool ean Supported On: 

inConversation() const; PM 


isCaseSensitive 

Returns true if the server has indicated it enforces case sensitivity; otherwise it returns 
false. 

Boolean 

isCaseSensitive() const; 

outstanding! ransactionCount 

Returns the number of transactions initiated by the client to which the server has not 
responded. 

unsigned long Supported On: 

outstandingTransactionCount() const; PM 

Returns the name of the topic about which the client is conversing. 


Supported On: 

PM 
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IString 

topic() const; 


Supported On: 

PM 


Conversation Initiation and Termination 

Use these members to begin and end conversations with DDE server applications. 

Attempts to initiate a conversation with the requested server application on the 
requested topic. The primary version of this overloaded member accepts the name of 
the requested application and topic as input and returns true if the conversation is 
successfully begun; otherwise it returns false. The version that accepts a server 
handle is provided along with the IDDEClientConversation;xlientHandle member to 
allow an object of this class to converse with a server without engaging in the normal 
conversation initialization. 

See clientHandle (p. 300) for information about that function. 

| virtual IDDEC1ientConversation& 

begin( const IWindowHandle& serverHandle); 


Exceptions 

IlnvalidParameter 

The server window handle is not valid. 


IlnvalidRequest 

The object is already in conversation with another application. 


virtual Boolean 

Supported On: 

begin( const char* 

applicationName, 

PM 

const char* 

topicName); 


Exceptions 

IlnvalidParameter 

The applicationName or topicName parameter is NULL or has a zero 
length. 


IlnvalidRequest 

The object is already in conversation with another application. 


IAccessError 

The operating system request to begin a conversation failed. 



Supported On: 

PM 


Ends the current conversation. 


virtual IDDEC1 ientConversation& Supported On: 

end (); PM 


Exceptions 

IlnvalidRequest The object is not in conversation with a server application. 
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Hot Link Information 

Use these members to obtain information about the hot links currently active in this object. 

hotLinkCount 

Returns a count of the number of hot links. 

unsigned long Supported On: 

hotLinkCount() const; PM 

.Adds all item and format pairs for which hot links have been established to the 
IDDEClientHotLinkSet passed in. 

Note: Include the iddecset.hpp header file when you use this function. 

See IDDEClientHotLinkSet (p. 317) for information about that class. 

IDDEClientConversation& Supported On: 

hotLinks( IDDEC1 ientHotLinkSet& hotLinkSet); PM 


Transactions 

Use these members to send transactions to the DDE server application. Most of them accept a 
string that identifies the format in which the data is rendered. The default is IDDE::textFormat, 
which specifies text format. Formats are standardized by various vendors, who describe them in 
their operating system or application documentation. 

_Requests the server to send a notification every time the value of the item changes. 

If the sendData argument is true, the data is sent with the notification in the requested 
format. If the pacing argument is true, the server is asked to wait for an 
acknowledgment from the client before sending a subsequent notification. 

This function accepts a format string that identifies the format in which the data is 
rendered. The default is IDDE::textFormat, which specifies the text format. 

Formats are standardized by various vendors, who describe them in their operating 
system or application documentation. 

virtual IDDEClientConversation& Supported On: 

beginHotLink( const char* item, PM 

I DDE::Format format = IDDE::textFormat, 

Boolean sendData = true. 

Boolean pacing = false); 
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Exceptions 

IlnvalidRequest 

The object is not in conversation with a server application, or a hot link for 
this item and format is already active or pending. 

IlnvalidParameter 

The item or format parameter is NULL or has a zero length. 

IAccessError 

The operating system request to post the DDE message to the server 
application failed. 


-.Requests the server to end a hot link on the specified item and format. This 
member accepts a format string that identifies the format in which the data is 
rendered. The default is IDDE::textFormat, which specifies the text format. 

Formats are standardized by various vendors, who describe them in their operating 
system or application documentation. 


virtual IDDEC1ientConversation& 
endHotLink( const char* item, 

I DDE::Format format = IDDE::textFormat); 


Supported On: 

PM 


Exceptions 

IlnvalidRequest 

The object is not in conversation with a server application, there is no hot 
link for this item and format, or an endHotLink(s) request for this item and 
format is pending. 

IlnvalidParameter 

The item or format parameter is NULL or has a zero length. 

IAccessError 

The operating system request to post the DDE message to the server 
application failed. 


-.Requests the server to end one or more hot links. If the item argument is specified, 
the server is requested to end all hot links on the item in all formats. If no arguments 
are provided, the server is requested to end all hot links on all items in all formats. 


virtual IDDEC1ientConversation& 
endHotLinks( const char* item = 0); 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The object is not in conversation with a server application. 


executeCommands 

Requests the server to execute one or more commands. 


virtual IDDEC1ientConversation& 
executeCommands( const void* commands, 

unsigned long commandLength); 


Supported On: 

PM 
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Exceptions 

IlnvalidRequest 

The object is not in conversation with a server application. 

IlnvalidParameter 

The commands or commandLength parameter is NULL. 

IAccessError 

The operating system request to post the DDE message to the server 


application failed. 


.Requests the server to set the specified item to the value of the data provided. This 

function accepts a format string that identifies the format in which the data is 
rendered. The default is IDDE::textFormat, which specifies the text format. 

Formats are standardized by various vendors, who describe them in their operating 
system or application documentation. 


virtual IDDEClientConversation& Supported On: 

pokeData( const char* item, PM 

const void* data, 
unsigned long dataLength, 

I DDE::Format format = IDDE::textFormat); 


Exceptions 

IlnvalidRequest 

The object is not in conversation with a server application. 

IlnvalidParameter 

Either the item, format, or data parameter is NULL, or the item or format 
parameter has a zero length. 

IAccessError 

The operating system request to post the DDE message to the server 
application failed. 


_. Requests the value of the item rendered in the specified format from the server. 
This function accepts a format string that identifies the format in which the data is 
rendered. The default is IDDEutextFormat, which specifies the text format. 

Formats are standardized by various vendors, who describe them in their operating 
system or application documentation. 


virtual IDDEC1ientConversation& 
requestData( const char* item, 

IDDE::Format format = IDDE::textFormat); 


Supported On: 

PM 


Exceptions 

IlnvalidRequest 

The object is not in conversation with a server application. 

IlnvalidParameter 

The item or format parameter is NULL or has a zero length. 

IAccessError 

The operating system request to post the DDE message to the server 


application failed. 
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Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members process events sent by the DDE server application. The 
dispatchHandlerEvent function is called whenever an event is sent to this object, and it calls one 
of the other appropriate members in this object to actually process the event. 

Typically, you do not need to override any of these members. If you want to provide some 
additional behavior before or after the event is processed, make sure that you call the 
IDDEClientConversation version of the member or unpredictable results can occur and the 
conversation may not be able to process further events from the DDE server application. You 
may need to override one of these members if the server application sends a DDE message not 
supported by the DDE protocol at that particular point in the conversation. You may need to do 
this because the IDDEClientConversation object throws these invalid events away. 

dispatchHandlerEvent 

Calls the appropriate virtual member if a DDE client conversation event is found. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM 


Exceptions 

IOutOfSystemResource The operating system request to write to a queue failed. See the text of the 
exception for further information. 
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Exceptions 

IAccessError This function has been called recursively, possibly violating DDE 

synchronization rules. Either construct this object with 
useEventThread=true, or avoid displaying dialog boxes in the event 
callback functions. 


-.Handles acknowledgments from server applications. 


virtual void 

handleAck( const IEvent& ackEvent); 
-.Handles data sent from server applications. 


Supported On: 

PM 


virtual void 

handleData( const IEvent& dataEvent); 


Supported On: 

PM 


handlelnitiateAck 

Handles acknowledgments from server applications to begin requests. 


virtual void 

handlelnitiateAck( const IEvent& initiateAckEvent); 


Supported On: 

PM 


handleTerminate 

Handles IDDETopicServer::endConversation requests from server applications. 

See endConversation (p. 348) for information about that member. 

virtual void Supported On: 

handleTerminate( const IEvent& terminateEvent); PM 


Event Processing 

Event-processing members are called to provide you with information when events are received 
from the DDE server application. To obtain the information provided by any of these virtual 
members, you must derive from this class and override the members. All of the members, except 
for the data member which is pure virtual, have default implementations so that you only need to 
override the members that provide information you wish to process. 

If you specify true for the useEventThread parameter of the IDDEClientConversation constructor, 
all of these members are invoked on a secondary thread. 
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acknowledged 

Provides generic acknowledgment from the server to a client initiated transaction. To 
get information provided by this function, provide a specialized implementation in the 
subclass. 

A positive acknowledgment can be sent in response to an 

IDDEClientConversation::beginHotLink or IDDEClientConversation::endHotLink 
member. A negative acknowledgment can be sent in response to the same two 
members, as well as to an IDDEClientConversation: uequestData member. 

See beginHotLink (p. 302), endHotLink (p. 303), and requestData (p. 304) for 
information about those members. 

If true is specified for the useEventThread argument of the IDDEClientConversation 
constructor, this member is called on a secondary thread. 

virtual void Supported On: 

acknowledged( IDDEC1ientAcknowledgeEvent& event); PM 

conversation Ended 

Notifies the client that the conversation is ending or ended. The conversation end can 
be initiated by either the client or the server, and can also be caused by an error 
condition in the IDDEClientConversation. 

virtual void Supported On: 

conversationEnded( IDDEC1 ientEndEvent& event); PM 

Provides data sent from the server. To get information provided by this member, 
provide a specialized implementation in the subclass. 

The data can be from an active hot link or as the result of the 

IDDEClientConversation::requestData member being called. See requestData (p. 304) 
for information about that member. 

If the server has requested an acknowledgment, the IDDEClientConversation object 
uses the return value from this member to determine whether to send a positive or 
negative acknowledgment. If the data is for a valid item and in the correct format, 
return true; otherwise, return false. 

If true is specified for the useEventThread argument of the IDDEClientConversation 
constructor, this member is called on a secondary thread. 

This member is pure virtual and must be overridden. 


© IBM Corp. 1992, 1995 


IDDEClientConversation 307 



IDDEClientConversation 


virtual Boolean Supported On: 

data( IDDEDataEvent& event) = 0; PM 

executeAcknowledged 

Positive or negative acknowledgment from the server as the result of the 
IDDEClientConversation::executeCommands member being called. To get 
information provided by this member, provide a specialized implementation in the 
subclass. See executeCommands (p. 303) for information about that member. 

If true is specified for the useEventThread argument of the IDDEClientConversation 
constructor, this member is called on a secondary thread. 

virtual void Supported On: 

executeAcknowledged( IDDEAcknowledgeExecuteEvent& event); PM 


hotLinklnform 

Notifies the client that the value of an item in the server for which the client has a 
hot link has changed. To get information provided by this member, provide a 
specialized implementation in the subclass. 

If the server has requested an acknowledgment, the IDDEClientConversation object 
uses the return value from this member to determine whether to send a positive or 
negative acknowledgment. If the client has an active hot link for this item and has 
requested that only notifications be sent, return true; otherwise, return false. The 
default behavior is to return true. 

If true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread. 

virtual Boolean 

hotLinkInform( IDDEC1 ientHotLinkEvent& event); 

pokeAcknowledged 

Positive or negative acknowledgment from the server as the result of the 
IDDEClientConversation: :pokeData member being called. To get information 
provided by this member, provide a specialized implementation in the subclass. If 
true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread. 

See pokeData (p. 304) and IDDETopicServer (p. 346) for information about that 
member and class. 


Supported On: 

PM 
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virtual void 

pokeAcknowledged( IDDEAcknowledgePokeEvent& event); 


Supported On: 

PM 


Miscellaneous Implementation 

The IDDEClientConversation object uses these members to provide portions of its 
implementation. Typically you do not need to override these members. 

endAIIHotLinks 

Called by the IDDEClientConversation: :endHotLinks function to update hot link 
instance data when one or more hot links are ending. The first version of this 
overloaded member is called when all hot links on an item are ending. The other 
version, which accepts no arguments, is used when all hot links are ending. 

See endHotLinks (p. 303) for information about that member. 

| virtual void 

endAl1HotLinks( const char* item); 


Exceptions 

IlnvalidParameter 

The item parameter has a zero length. 

IAccessError 

The operating system request to post the DDE message to the server 
application failed. 

IlnvalidRequest 

There are no active hot links for this item, or an endHotLinks() request for 
this item is pending. 

virtual void 
endAl 1 HotLinks(); 

Supported On: 

PM 

Exceptions 

IAccessError 

The operating system request to post the DDE message to the server 
application failed. 

IlnvalidRequest 

There are no active hot links, or an endHotLinks() request for all hot links 
is pending. 


Supported On: 

PM 


findTransaction 

Called by any of the handle members, such as IDDEClientConversation::handleAck 
and IDDEClientConversation: :handleData, when it is suspected that the server is not 
sending acknowledgments when it should. If this member determines that the 
suspicion is correct, it simulates acknowledgments for the transactions that are waiting 
for these acknowledgments. 
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virtual Boolean 

findTransaction( const IEvent& event. 

Boolean removeMatch = false); 


Supported On: 

PM 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

IEvent 

IDDEEndEvent 

IDDEClientEndEvent 


_.None. 


_iddeevt.hpp 
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312 


The IDDEClientEndEvent class provides event information to a client application 
when a conversation is ended or ending. 

An object of this class is created when an IDDEClientConversation object needs to 
notify the application that a conversation is ending or ended. You do not construct 
objects of this class. See IDDEClientConversation (p. 297) for information about that 
class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDEClientConversation objects. 


IDDEClientEndEvent 


IDDECl ientEndEvent( const IEvent& ddeEvent, Supported On: 

Source endSource, PM 

IString application, 

IString topic); 
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"IDDEClientEndEvent 

~IDDEClientEndEvent(); Supported On: 

PM 

Event Information 

Use these members to query information about the conversation that is ending. 

_ Returns the name of the server application for the conversation that is ending or 
ended. 


IString Supported On: 

application() const; PM 

Returns the name of the topic supported by the conversation that is ending or ended. 


IString Supported On: 

topic() const; PM 


Inherited Public Functions 


IDDEEndEvent 

sourceOfEnd 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 
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IBase 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

IEvent 

IDDEEvent 

IDDESetAcknowledgelnfoEvent 

IDDEClientHotLinkEvent 


_.None. 


__iddeevt.hpp 
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The IDDEClientHotLinkEvent class provides information to a client application when 
a hot link item change notification is sent by a server application. 

An object of this class is created when an IDDEClientConversation object needs to 
pass a hot link notification to the client application. An object of this class for each 
active hot link is also kept in a set by IDDEClientConversation objects to keep track 
of active hot links. You do not construct objects of this class. See 
IDDEClientConversation (p. 297) for information about that class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are usually created and deleted for you by IDDEClientConversation objects. 


IDDEClientHotLinkEvent 

[J IDDEClientHotLinkEvent( const IEvent& ddeEvent); Supported On: 

PM 
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IDDEClientHotLinkEvent 


§ IDDEClientHotLinkEvent( Supported On: 

const IDDEC1 ientHotLinkEvent& ddeEvent); PM 

"IDDEClientHotLinkEvent 

"IDDECl i entHotLi nkEvent (); Supported On: 

PM 


Event Information 

Use these members to query information about the hot link event. 


isAckRequested 

Returns true if the server has requested an acknowledgment of receipt of the 
notification. The IDDEClientConversation object automatically sends the 
acknowledgment when it is requested. 

See IDDEClientConversation (p. 297) for information about that class. 

Boolean Supported On: 

isAckRequested() const; PM 


is Data Requested 

Returns true if the hot link is a data hot link. False is returned if it is a notification 
hot link. This function is only pertinent for objects of this class used to keep track of 
active hot links (contained in an IDDEClientHotLinkSet object). All other objects of 
this class are created for notifications sent by non-data hot links. 

See IDDEClientHotLinkSet (p. 317) for information about that class. 

Boolean Supported On: 

isDataRequested() const; PM 


Inherited Public Functions 


IDDESetAeknowledgelnfoEvent 

setApplicationBusy 

setApplicationSpecificData 

setMessageNotUnderstood 
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The IDDEClientHotLinkSet class is a set that was created using the ISet template 
class. The set contains pointers to IDDEClientHotLinkEvent objects. See 
IDDEClientHotLinkEvent (p. 314) for information about that class. 

An IDDEClientConversation object creates objects of this class to keep track of the 
active hot links for the conversation. An application creates an object of this class to 
call the IDDEClientConversation: :hotLinks member to get the current set of active hot 
links. If you remove individual elements of the set, delete the 
IDDEClientHotLinkEvent to which each element points or the memory is not 
recovered. See IDDEClientConversation (p. 297), and hotLinks (p. 302) for 
information about that class and member. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDDEClientHotLinkSet 

IDDECl i entHotLi nkSet (); Supported On: 

PM 

You can construct objects of this class using the default constructor, which does not 
accept any arguments. 
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IDDEClientHotLinkSet 


"IDDEClientHotLinkSet 

This member removes all the elements from the set, and deletes them. 


MDDEC1ientHotLinkSet (); 


Supported On: 

PM 
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The IDDEDataEvent class provides event information and data to a client application. 

An object of this class is created when an IDDEClientConversation object needs to 
pass data sent from a server to the client application. This can result from a 
requestData request or from an active hot link. You do not construct objects of this 
class. See IDDEClientConversation (p. 297) and requestData (p. 304) for information 
about that class and member. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are usually created and deleted for you by IDDEClientConversation objects. 

IDDEDataEvent 


IDDEDataEvent( const IEvent& ddeEvent); 


Supported On: 

PM 
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IDDEDataEvent 


"IDDEDataEvent 

"IDDEDataEvent(); 


Supported On: 

PM 


Event Information 

Use these members to query the data and other related information from the event. 

Returns the data provided by the server. 

Note: The IDDEDataEvent::data member's IString is constructed from a void* and 
length. For character strings, if the terminating NULL is included in the length, it is 
in the buffer. Before performing string operations such as concatenation on this 
string, use IString::stripTrailing to strip any trailing NULL character. 

See IString (Vol. I) and stripTrailing (Vol. I) for information about that class and 
member. 

IString Supported On: 

data() const; PM 


isAckRequested 

Returns true if the server has requested an acknowledgment of receipt of the data. 

The IDDEClientConversation object automatically sends the acknowledgment when it 
is requested. 

See IDDEClientConversation (p. 297) for information about that class. 

Boolean 

isAckRequested() const; 

isDataFromHotLink 

Returns true if the data is being sent as the result of an active hot link. Returns false 
if the data is sent in response to an IDDEClientConversation: uequestData call. 

See requestData (p. 304) for information about that member. 

Bool ean Supported On: 

isDataFromHotLink() const; PM 


Supported On: 

PM 
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Inherited Protected Data 
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The IDDEEndEvent class provides event information to a server application when a 
conversation is ended or ending. 

An object of this class is created when an IDDETopicServer object needs to notify 
the application that a conversation is ending or ended. You do not construct objects 
of this class. See IDDETopicServer (p. 346) for information about that class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are usually created and deleted for you by IDDETopicServer objects. 


IDDEEndEvent 


IDDEEndEvent( const IEvent& ddeEvent, 
Source endSource); 


Supported On: 

PM 
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IDDEEndEvent 


TDDEEndEvent 


"IDDEEndEventO; 


Supported On: 

PM 


Event Information 

Use these members and enumerations to determine the initiator or cause of the conversation 
termination. 

- Returns one of the values of the IDDEEndEvent::Source enumeration indicating the 
source of the ending of the conversation. 

See Source (p. 324) for information about that enumeration. 

Source Supported On: 

sourceOfEndQ const; PM 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 
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IVBase 

asDebuglnfo 
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IDDEEndEvent 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Source { 
client, 
server, 
error 
}; 


Enumeration that is used to defined the possible sources of an end to a conversation: 

client 

Indicates that the client initiated the conversation's end. 
server 

Indicates that the server initiated the conversation's end. 

error 

Indicates that an error in a routine entered from the dispatcher would cause an 
exception to be thrown and the application would not have an opportunity to 
catch the exception. Since this situation could cause this application and the 
application being conversed with to abnormally end, this application is called 
back with an IDDEEndEvent object. The conversation is also terminated at this 
point. 
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IDDEEvent is the base class for most Dynamic Data Exchange (DDE) event classes. 

An object of this class, or one of its subclasses, is created when an 
IDDEClientConversation object or IDDETopicServer object needs to pass information 
to the client or server application. You do not construct objects of this class. See 
IDDEClientConversation (p. 297) and IDDETopicServer (p. 346) for information 
about those classes. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are usually created and deleted for you by IDDETopicServer or 
IDDEClientConversation objects. 


IDDEEvent 


[] IDDEEvent( const IEvent& ddeEvent); 


Supported On: 

PM 
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IDDEEvent 


2 IDDEEvent( const IDDEEvent& ddeEvent); 

"IDDEEvent 


Supported On: 

PM 


~IDDEEvent(); Supported On: 

PM 

Event Information 

Use these members to query information about the item and format of the data that the event is 
dealing with. 

Returns the name of the format. 


IString 

format() const; 

Returns the name of the item 


IString Supported On: 

item() const; PM 


Supported On: 

PM 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 
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IDDEEvent 


IBase 

asString 

messageText 

version 


Protected Functions 
Implementation 

Derived classes use these members to set and obtain the attributes of this class. 

Returns the data buffer. 

Note: The IDDEEvent::buffer member's IString is constructed from a void* and 
length. For character strings, if the terminating NULL is included in the length, it is 
in the buffer. Before performing string operations such as concatenation on this 
string, use IString: :stripTrailing to strip any trailing NULL character. 

See IString (Vol. I) and stripTrailing (Vol. I) for information about that class and 
member. 


IString Supported On: 

buffer() const; PM 

...Sets the data into the data buffer. 

IDDEEvent& Supported On: 

setBuffer( IString dataBuffer); PM 

...Sets the status field of the event. 

IDDEEvent& Supported On: 

setStatus( unsigned short status); PM 


Returns the status of the event. 


unsigned short Supported On: 

status() const; PM 


Inherited Protected Data 
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unrecoverable 
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The IDDEExecuteEvent class provides event information to a server application when 
a client has asked the server to execute a command string. 

An object of this class is created when an IDDETopicServer object needs to pass an 
executeCommands request to the server application. You do not construct objects of 
this class. See IDDETopicServer (p. 346) and executeCommands (p. 354) for 
information about that class and function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDETopicServer objects. 

IDDEExecuteEvent 

IDDEExecuteEvent ( const IEvent& ddeEvent); Supported On: 

PM 
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IDDEExecuteEvent 


~IDDEExecuteEvent 

_ IDDEExecuteEvent(); 


Supported On: 

PM 


Event Information 

Use these members to query the command string sent by the DDE client application. 

_ Returns the command string that the client has asked the server to execute. 

Note: The IDDEExecuteEvent: xommands member's IString is constructed from a 
void* and length. For character strings, if the terminating NULL is included in the 
length, it is in the buffer. Before performing string operations such as concatenation 
on this string, use IString: :stripTrailing to strip any trailing NULL character. 

See IString (Vol. I) and stripTrailing (Vol. I) for information about that class and 
member. 

IString Supported On: 

commands() const; PM 


Inherited Public Functions 
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The IDDEPokeEvent class provides event information to a server application when a 
client has asked the server to set an item to a new value. 

An object of this class is created when an IDDETopicServer object needs to pass a 
pokeData request to the server application. You do not construct objects of this class. 
See IDDETopicServer (p. 346) and pokeData (p. 355) for information about that class 
and member. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDETopicServer objects. 

IDDEPokeEvent 

IDDEPokeEvent( const IEvent& ddeEvent); Supported On: 

PM 
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IDDEPokeEvent 


"IDDEPokeEvent 

"IDDEPokeEvent(); 


Supported On: 

PM 


Event Information 

Use these members to query the data that the DDE client application has sent to be poked. 

_ Returns the data that the client asked the server to set an item's value to. 

Note: The IDDEPokeEvent::pokedData member's IString is constructed from a void* 
and length. For character strings, if the terminating NULL is included in the length, 
it is in the buffer. Before performing string operations such as concatenation on this 
string, use IString: :stripTrailing to strip any trailing NULL character. 

See IString (Vol. I) and stripTrailing (Vol. I) for information about that class and 
member. 

IString Supported On: 

pokedData() const; PM 
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The IDDERequestDataEvent class provides event information to a server application 
when a client has requested data. 

An object of this class is created when an IDDETopicServer object needs to pass 
requests for data to the server application. You do not construct objects of this class. 
See IDDETopicServer (p. 346) for information about that class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDETopicServer objects. 

IDDERequestDataEvent 

IDDERequestDataEvent( const IEvent& ddeEvent); Supported On: 

PM 
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"IDDERequestDataEvent 

"IDDERequestDataEventO; Supported On: 

PM 


Event Information 

Use these members to provide the data requested by the DDE client application and to set the 
related attributes of the event. 

_Sets the request acknowledgment flag. 

IDDERequestDataEvent& Supported On: 

requestAck(); PM 

Provides the requested data so it can be sent to the client. This member is 
overloaded so that either buffers of data or character strings can be easily sent. 

Q IDDERequestDataEvent& Supported On: 

setData( const void* dataBuffer, PM 

unsigned long dataLength); 


£ IDDERequestDataEvent& Supported On: 


setData( const 

char* dataString); 


PM 

Inherited Public Functions 
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The IDDEServerAcknowledgeEvent class provides event information to a server 
application regarding an acknowledgment from a client. 

An object of this class is created when an IDDETopicServer object needs to pass 
information about an acknowledgment to the server application. You do not construct 
objects of this class. See IDDETopicServer (p. 346) for information about that class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDETopicServer objects. 

IDDEServerAcknowledgeEvent 

IDDEServerAcknowledgeEvent( const IEvent& ddeEvent); Supported On: 

PM 
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IDDEServerAcknowledgeEvent 


IDDEServerAcknowledgeEvent 

IDDEServerAcknowledgeEvent (); Supported On: 

PM 


Event Information 

Use these members to query information about an acknowledgment received from a DDE client 
application. 

Returns the data the server provided to the client. 

Note: The IDDEServerAcknowledgeEvent:: data member's IString is constructed 
from a void* and length. For character strings, if the terminating NULL is included 
in the length, it is in the buffer. Before performing string operations such as 
concatenation on this string, use IString::stripTrailing to strip any trailing NULL 
character. 

See IString (Vol. I) and stripTrailing (Vol. I) for information about that class and 
member. 

IString Supported On: 

data() const; PM 

isAckToHotLinkUpdate 

Returns true if the acknowledgment is in response to 

IDDETopicServer::hotLinkUpdate being called. It returns false if it is in response to 
data being provided for an IDDETopicServer::requestData call. 

See hotLinkUpdate (p. 349) and requestData (p. 355) for information about those 
members. 

Bool ean Supported On: 

i sAckToHotLinkUpdate() const; PM 


Inherited Public Functions 
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The IDDEServerHotLinkEvent class provides event information to a server 
application when a client has asked the server to begin a hot link. 

An object of this class is created when an IDDETopicServer object needs to pass a 
beginHotLink request to the server application. You do not construct objects of this 
class. See IDDETopicServer (p. 346) and beginHotLink (p. 354) for information 
about that class and function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDETopicServer objects. 


IDDEServerHotLinkEvent 

IDDEServerHotLinkEvent( const IEvent& ddeEvent); Supported On: 

PM 
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~IDDEServerHotLinkEvent 

"IDDEServerHotLinkEvent (); Supported On: 

PM 


Event Information 

Use these members to query information about the hot link associated with this event. 


is Data Requested 

Returns true if the client application has requested a data hot link. Returns false if a 
notification link has been requested. 

Boolean 

isDataRequested() const; 

isPacingRequested 

Returns true if the client application has requested the server to request an 
acknowledgment from the client whenever it sends data or a notification. 

Boolean Supported On: 

isPacingRequested() const; PM 


Supported On: 

PM 


Inherited Public Functions 


IDDESetAeknowledgelnfoEvent 

setApplicationBusy 

setApplicationSpecificData 

setMessageNotUnderstood 


IDDEEvent 

format 

item 



IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


© IBM Corp. 1992, 1995 


IDDEServerHotLinkEvent 341 






IDDEServerHotLinkEvent 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDDEEvent 

buffer 

setBuffer 

setStatus 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



342 Open Class Library Reference 






IDDESetAcknowledgelnfoEvent 



IDDESetAcknowledgelnfoEvent 


IBase 

IVBase 

IEvent 

IDDEEvent 

IDDESetAcknowledgelnfoEvent 


IDDEClientHotLinkEvent 

IDDEPokeEvent 

IDDEDataEvent 

IDDERequestDataEvent 

IDDEExecuteEvent 

IDDEServerHotLinkEvent 


_-iddeevt.hpp 




Member 

Page 

Member 

Page 

Constructor 

343 

setMessageNotUnderstood 

344 

setApplicationBusy 

344 

'IDDESetAcknowledgelnfoEvent 

344 

setApplicationSpecificData 

344 




The IDDESetAcknowledgelnfoEvent class is the base class for Dynamic Data 
Exchange (DDE) event information classes that need to set acknowledgment 
information. 

An object of a subclass of IDDESetAcknowledgelnfoEvent is only created for events 
that the application can respond to with a negative acknowledgment. You do not 
construct objects of this class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class, although normally you will never need to do 
so. These events are normally created and deleted for you by IDDETopicServer or 
IDDEClientConversation objects. 


IDDESetAcknowledgelnfoEvent 
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[] IDDESetAcknowledgeInfoEvent( const IEvent& ddeEvent); Supported On: 

PM 


| IDDESetAcknowledgeInfoEvent( Supported On: 

const IDDESetAcknowledgeInfoEvent& ddeEvent); PM 

"IDDESetAcknowledgelnfoEvent 

'IDDESetAcknowledgeInfoEvent(); Supported On: 

PM 


Event Information 

Use these members to set the information for an acknowledgment being sent to the DDE partner 
application. 

setApplicationBusy 

Sets the application busy flag. This is used by a client or server application to 
indicate why a request or response to a request cannot be processed. 

IDDESetAcknowledgeInfoEvent& 
setAppl icationBusy (); 

setApplicationSpecificData 

Sets application-specific information. This can be used when a client and server 
application have a pre-defined protocol for exchanging information. 

IDDESetAcknowledgeInfoEvent& Supported On: 

setAppl icationSpecificData( unsigned char appl icationData); PM 

setMessageNotllnderstood 

Sets the message not understood flag. This is used by a client or server application to 
indicate why a request or response to a request cannot be processed. 

IDDESetAcknowledgeInfoEvent& Supported On: 

setMessageNotllnderstood (); PM 


Supported On: 

PM 
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Inherited Public Functions 


IDDEEvent 

format 

item 



IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDDEEvent 

buffer 

setBuffer 

setStatus 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDDETopicServer 


IBase 

IVBase 

IHandler 

IDDETopicServer 


_.None. 

—iddetsrv.hpp 


Member 

Page 

Member 

Page 

Constructor 

347 

handlePoke 

352 

acceptConversation 

353 

handleRequest 

352 

acknowledged 

353 

handleTerminate 

352 

application 

349 

handleUnadvise 

352 

beginConversation 

348 

hotLinkCount 

349 

beginHotLink 

354 

hotLinkEnded 

355 

conversationCount 

349 

hotLinkUpdate 

349 

conversationEnded 

354 

pokeData 

355 

di spatchHandlerE vent 

351 

removeLink 

352 

endConversation 

348 

requestData 

355 

executeCommands 

354 

requestHotLinkData 

356 

handleAck 

351 

serverHandle 

350 

handleAdvise 

351 

topic 

350 

handleExecute 

351 

'IDDETopicServer 

348 

handlelnitiate 

351 




The IDDETopicServer class adds Dynamic Data Exchange (DDE) server function to 
an application. 

Create an object of this class for each topic you want to support in a DDE server 
application. The object manages all window, shared memory, and atom table 
processing. 

This class uses a window to communicate; therefore, window message processing 
must occur. This means that ICurrentThread::processMsgs must be called. There are 
several ways for this to occur. Normally, this is accomplished by calling 
IApplication::current().run(). See processMsgs (Vol. II), current (Vol. II), and run 
(Vol. II) for information about those members. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IDDETopicServer 

IDDETopicServer( const char* appl i cati onName, Supported On: 

const char* supportedTopic, PM 

IFrameWindow* owner = 0, 

Boolean useEventThread = true); 

You can construct objects of this class in the following way. 

The constructor accepts the following two required arguments and two optional 

arguments. 

• The name of the application to which the topic server belongs (required) 

• The name of the topic that the topic server supports (required) 

• The third argument is optional, but highly recommended if the application has a 
main frame window. IDDETopicServer creates an IFrameWindow object, which 
must be destructed for the application to end normally. Specifying this argument 
guarantees that this window is destructed when the main frame window is closed. 
The alternative is to ensure that all objects of IDDETopicServer are deleted 
before attempting to end the application. See IFrameWindow (Vol. II) for 
information about that class. 

• The fourth argument is also optional, but also highly recommended if the 
application must do any extensive processing or interacts with the user during 
any of the callback functions. Specifying true allows the IDDETopicServer 
object to create a secondary thread to process incoming events. This prevents 
problems with window message processing because the thread is created without 
a message queue. If you specify false, no secondary thread is created and you 
should return promptly from all callback functions. 


Exceptions 

IlnvalidParameter 

The applicationName or supportedTopic parameter is NULL or has a zero 
length. 

IOutOfSystemResource 

The operating system request for either an event semaphore or a queue 
failed. See the text of the exception for further information. 


© IBM Corp. 1992, 1995 


IDDETopicServer 347 




IDDET opicServer 


"IDDETopicServer 

The destructor will end all conversations with all DDE client applications as part of 
its cleanup. 

virtual Supported On: 

'IDDETopicServer(); PM 


Conversation Initiation and Termination 

Use these members to begin and end conversations with DDE client applications. 

beginConversation 

This is provided along with the IDDETopicServer::serverHandle member to allow a 
topic server to get in conversation with a client without engaging in the normal 
conversation initialization. See serverHandle (p. 350) for information about that 
member. 

This member sets the window handle associated with the client conversation. To 
initiate a conversation in this manner, the client and server application must have their 
own method for exchanging their window handles. 


virtual IDDETopicServer& Supported On: 

beginConversation( const IWindowHandl e& cl ientHandl e); PM 


Exceptions 

IlnvalidParameter 

The client window handle is not valid. 

IlnvalidRequest 

A conversation with this client window is already active. 


endConversation 

Ends a conversation with a DDE client. 

Supported On: 

PM 


Exceptions 

IlnvalidRequest There is no active conversation identified by this ID. 


virtual IDDETopicServer& 
endConversation( unsigned long conversationld); 


Hot Link Updates 

Use these members to initiate the sending of hot link updates to DDE client applications. 
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hotLinkUpdate 

Sends either data or a change notification for items whose data has changed to all 
clients who have an active hot link for this item. 

lDDETopicServer::requestHotLinkData is called for each format that has an active hot 
link and requires data. The number of hot links for which data or a notification is 
sent is returned to the caller. See requestHotLinkData (p. 356) for information about 
that member. 

If there is an outstanding acknowledgment for a hot link, the notification is not sent 
to the client to which the hot link belongs. When the acknowledgment is satisfied, a 
notification is sent to the client with the most current data if it is a data hot link. 


unsigned long Supported On: 

hotLinkllpdate( const char* item); PM 


Exceptions 

IlnvalidParameter 

The item parameter is NULL or has a zero length. 

IAccessError 

The operating system request to post the DDE message to a client 


application failed. 

IlnvalidRequest 

There is no active hot link for this item and format. 


Server Information 

Use these members to query information about the attributes of objects of this class. 

_ Returns the name of the server application. 

IString 

application)) const; 

conversationCount 

Returns the number of conversations in which the topic server is currently engaged. 

unsigned long Supported On: 

conversationCount() const; PM 


Supported On: 

PM 


hotLinkCount 

Returns the number of hot links in which the topic server is currently engaged. 

unsigned long Supported On: 

hotLinkCount)) const; PM 
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—Returns the window handle of the topic server. This is provided along with the 
IDDETopicServer::beginConversation member to allow a topic server to get in 
conversation with a client without engaging in the normal conversation initialization. 
Only a client is normally allowed to initiate a conversation. See beginConversation 
(p. 348) for information about that member. 

IWi ndowHandle 
serverHandle() const; 

Returns the name of the supported topic. 

IString Supported On: 

topic() const; PM 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members process events sent by DDE client applications. The 
dispatchHandlerEvent function is called whenever an event is sent to this object, and it calls one 
of the other appropriate members in this object to actually process the event. 

Typically, you do not need to override any of these members. If you wish to provide some 
additional behavior before or after the event is processed make sure that you call the 
IDDETopicServer version of the member or unpredictable results can occur and the conversation 
may not be able to process further events from the DDE client application. You may need to 
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override one of these members if the client application sends a DDE message not supported by 
the DDE protocol at that particular point in the conversation. You may need to do this because 
the IDDETopicServer object throws these invalid events away. 


dispatchHandlerEvent 

Calls the appropriate virtual member if a DDE topic server event is found. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM 


Exceptions 

IOutOfSystemResource 

The operating system request to write to a queue failed. See the text of the 
exception for further information. 

IAccessError 

This function has been called recursively, possibly violating DDE 
synchronization rules. Either construct this object with 
useEventThread=true, or avoid displaying dialog boxes in the event 
callback functions. 


.Handles acknowledgments from client applications. 


virtual void 

handleAck( const IEvent& ackEvent); 


Supported On: 

PM 


handleAdvise 

Handles IDDETopicServer::beginHotLink requests from client applications. See 
beginHotLink (p. 354) for information about that member. 


virtual void 

handleAdvise( const IEvent& adviseEvent); 


Supported On: 

PM 


handleExecute 

Handles !DDETopicServer::executeCommands requests from client applications. See 
executeCommands (p. 354) for information about that member. 


virtual void 

handleExecute( const IEvent& executeEvent); 


Supported On: 

PM 


handlelnitiate 

Handles begin requests from client applications. 
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virtual void Supported On: 

handlelnitiate( const IEvent& initiateEvent); PM 

—Handles IDDETopicServer::pokeData requests from client applications. See 
pokeData (p. 355) for information about that member. 

virtual void Supported On: 

handlePoke( const IEvent& pokeEvent); PM 


handleRequest 

Handles IDDETopicServer::requestData requests from client applications. See 
requestData (p. 355) for information about that member. 


virtual void 

handleRequest( const IEvent& requestEvent); 


Supported On: 

PM 


handleTerminate 

Handles end requests from client applications. 


virtual void 

handleTerminate( const IEvent& terminateEvent); 


Supported On: 

PM 


handleUnadvise 

Handles IDDETopicServer::hotLinkEnded requests from client applications. See 
hotLinkEnded (p. 355) for information about that member. 

virtual void Supported On: 

handleUnadvise( const IEvent& unadviseEvent); PM 

—Called by the !DDETopicServer::handleUnadvise function to update hot link 
information when a client ends a hot link. See handleUnadvise (p. 352) for 
information about that member. 


virtual Boolean Supported On: 

removeLink( IString item, PM 

IString format, 

unsigned long conversationld); 


Event Processing 

Event-processing members provide you with information when events, typically requests, are 
received from a DDE client application. To obtain the information provided by any of these 
virtual members, and to support the requested transactions, derive from this class and override 
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the members. All of the members, except for the requestData member which is pure virtual, 
have default implementations so that you only need to override the functions that you want to 
support or use. 

If you specify true for the useEventThread parameter of the IDDETopicServer constructor, all of 
these members except for acceptConversation and in some cases requestHotLinkData, are 
invoked on a secondary thread. 


acceptConversation 

Informs the server that a client is asking to begin a conversation. The topic server 
calls this member if the application and topic match, ignoring mismatches due to 
different cases. The application should return promptly from this member because the 
request is sent, not posted, by the client application. Therefore, this member is 
always called in the main thread. 

Return true if the conversation is accepted. (The application can indicate it enforces 
case sensitivity by calling IDDEBeginEvent::setCaseSensitive. See setCaseSensitive 
(p. 291) for information about that member.) 

If the conversation request is rejected, return false so the topic server does not accept 
the conversation. The default behavior is to return true. 

virtual Boolean Supported On: 

acceptConversation( unsigned long conversationld, PM 

IDDEBeginEvent& event); 


acknowledged 

Informs the server that a client has acknowledged the receipt of data or notification of 
changed hot link data. If true is specified for the useEventThread argument of the 
IDDETopicServer constructor, this member is called on a secondary thread. 

Note: The IDDETopicServer::hotLinkUpdate and 

IDDETopicServer::endConversation members must not be called from this member. 
Otherwise, a dead-lock can occur. 

See hotLinkUpdate (p. 349) and endConversation (p. 348) for information about those 
members. 

virtual void Supported On: 

acknowledged( unsigned long conversationld, PM 

IDDEServerAcknowledgeEvent& event); 
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_ Informs the server that a client is requesting a hot link on a particular item and 
format. If the application supports hot links for this item and format, return true so 
the topic server sends the client a positive acknowledgment. The 
IDDETopicServer::hotLinkUpdate member is provided for sending either data or a 
notification when the item's value changes. See hotLinkUpdate (p. 349) for 
information about that member. 

If the application does not support this hot link request, it should use any appropriate 
members of the IDDEServerHotLinkEvent object to indicate the reason and return 
false. This causes the topic server to send a negative acknowledgment to the client. 
See IDDEServerHotLinkEvent (p. 340) for information about that class. 

If true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread. 

The default behavior is to return false. 

virtual Boolean Supported On: 

beginHotLink( unsigned long conversationld, PM 

IDDEServerHotLinkEvent& event); 


conversationEnded 

Notifies the server that the conversation is ending or ended. The conversation end 
can be initiated by either the client or the server, and can also be caused by an error 
condition in the IDDEClientConversation. See IDDEClientConversation (p. 297) for 
information about that class. 

If true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread. 

virtual void Supported On: 

conversationEnded( unsigned long conversationld, PM 

IDDEEndEvent& event); 


executeCommands 

Informs the server that a client is requesting the application to execute a string of one 
or more commands. If the application supports the request and successfully executes 
the commands, return true so the topic server sends the client a positive 
acknowledgment. If the application cannot honor this request, it should use any 
appropriate members of the IDDEExecuteEvent object to indicate the reason and 
return false. This causes the topic server to send a negative acknowledgment to the 
client. The default behavior is to return false. See IDDEExecuteEvent (p. 328) for 
information about that class. 
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If true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread. 


virtual Boolean 

executeCommands( unsigned long conversationld, 
IDDEExecuteEvent& event); 


Supported On: 

PM 


hotLinkEnded 

Informs the server that a client has ended one or more hot links. If the format is a 
0-length string, all hot links on the specified item are ended. If the item is a 0-length 
string, all hot links with this client are ended. 

If true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread. 

virtual void Supported On: 

hotLinkEnded( unsigned long conversationld, PM 

IDDEEvent& event); 

_ Informs the server that a client is requesting it to set an item to the new value 
provided by the client. If the application is able to honor the request, return true so 
the topic server sends the client a positive acknowledgment. If the application is 
unable to honor the request, it should use any appropriate members of the 
IDDEPokeEvent object to indicate the reason and return false. This causes the topic 
server to send a negative acknowledgment to the client. The default behavior is to 
return false. See IDDEPokeEvent (p. 331) for information about that class. 

If true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread. 

virtual Boolean 

pokeData( unsigned long conversationld, 

IDDEPokeEvent& event); 

_ Informs the server that a client is requesting data for an item in a specified format. 

If the request is for an item and format the application supports, it should provide the 
data using the IDDERequestDataEvent::setData member and return true. The 
application can also request an acknowledgment from the client when it has received 
the data using the IDDERequestDataEvent::requestAck function. See setData (p. 335) 
and requestAck (p. 335) for information about those members. 

If the application cannot provide the data, it can indicate one of several reasons using 
the appropriate members of IDDERequestDataEvent and return false. This causes the 
topic server to send the client a negative acknowledgment. This function is pure 


Supported On: 

PM 
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virtual and must be overridden. See IDDERequestDataEvent (p. 334) for information 
about that class. 

If true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread. 


virtual Boolean 

requestData( unsigned long conversationld, 

IDDERequestDataEvent& event) = 0; 


Supported On: 

PM 


requestHotLinkData 

Informs the server that data is required for an item in a specified format. This 
member is called once for each format that has an active hot link that requires data 
when the server calls the IDDETopicServer: :hotLinkUpdate member for an item. The 
server calls the hotLinkUpdate member when an item with active hot links changes. 
See hotLinkUpdate (p. 349) for information about that member. 

There is no need for this member to call the IDDERequestDataEvent: :requestAck 
member because the topic server does this automatically for all hot links that have 
pacing active. (The server can request an acknowledgment even if pacing is not 
active.) For hot links that have pacing active and an outstanding acknowledgment, 
the update is not sent. See requestAck (p. 335) for information about that member. 

When the acknowledgment is received, the topic server requests the latest update if 
the data has changed while the acknowledgment was outstanding. In these cases, if 
true is specified for the useEventThread argument of the IDDETopicServer 
constructor, this member is called on a secondary thread; otherwise, it is called in the 
main thread. 

Note: The IDDETopicServer::hotLinkUpdate and 

IDDETopicServer::endConversation members must not be called from this member. 
Otherwise, a dead-lock can occur. See hotLinkUpdate (p. 349) and endConversation 
(p. 348) for information about those members. 

virtual void Supported On: 

requestHotLinkData( IDDERequestDataEvent& event); PM 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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.Inherits from none. 

_.None. 


_-idmcomm.hpp 


Member 

Page 

Member 

Page 

any 

359 

rfProcess 

360 

binary 

359 

rfSharedMem 

361 

binaryData 

359 

rfText 

361 

bitmap 

359 

rfUnknown 

361 

container 

359 

rmAny 

361 

containerObject 

359 

rmDiscard 

361 

debugSupport 

358 

rmFile 

361 

file 

359 

rmLibrary 

361 

icon 

359 

rmObject 

361 

menultem 

359 

rmPrint 

362 

plainText 

360 

text 

360 

rfAny 

360 

toolBarButton 

360 

rfObject 

360 

unknown 

360 


The following enumerations and rendering mechanisms and formats (RMFs) are 
available for all the direct manipulation classes. 


Public Data 
Diagnostics 

Use these flags to activate full debug support. 


debugSupport 

Set this flag to true to enable full debug support. When set to true, this flag will 
disable screen locking during direct manipulation. The default setting for this flag is 
false. 

static Boolean Supported On: 

debugSupport; PM 
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Drag Item Types 

Use these strings to query or set drag item types. 

Any type. 

static Type Supported On: 

any; PM 

Generic binary item type. 


static Type Supported On: 

binary; PM 

_Binary data item type. 


static Type Supported On: 

binaryData; PM 

..Bitmap item type. 


static Type Supported On: 

bitmap; PM 

...Container item type. 


static Type 
container; 


Supported On: 

PM 


containerObject 

Container object item type. 

static Type 
containerObject; 

File item type. 

static Type 
file; 

Icon item type. 

static Type 
icon; 

-Menu item drag item type. 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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static Type Supported On: 

menultem; PM 

...Plain text drag item type. 


static Type Supported On: 

plainText; PM 

.Generic text drag item type. 


static Type 
text; 


Supported On: 

PM 


toolBarButton 

Tool bar button drag item type. 

static Type Supported On: 

toolBarButton; PM 

...Unknown drag item type. 


static Type 
unknown; 


Supported On: 

PM 


Rendering Formats 

Use these strings to query or set rendering formats that are supported by the User Interface Class 
Library. 


Any rendering format. 

static RF Supported On: 

rfAny; PM 

.. Workplace Shell object rendering format. 


static RF Supported On: 

rfObject; PM 

...Process rendering format. ("="+PID suffix added for intraprocess rendering.) 


static RF 
rfProcess; 


Supported On: 

PM 
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rfSharedMem 

Shared memory rendering format. 

static RF Supported On: 

rfSharedMem; PM 

.Text rendering format (Used if text length <= 255 and text does not contain 
embedded NULLs) 


static RF Supported On: 

rfText; PM 

—Unknown rendering format. 


static RF 
rfUnknown; 


Supported On: 

PM 


Rendering Mechanisms 

Use these strings to query or set rendering mechanisms that are supported by the User Interface 
Class Library. 

Any support. 

static RM 
rmAny; 

-Discard support. 

static RM 
rmDiscard; 

..File support. 

static RM 
rmFi 1 e; 

-User Interface Class Library support. 

static RM Supported On: 

rmLibrary; PM 

-Workplace Shell object support. 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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static RM 
rmObject; 

Print support. 


Supported On: 

PM 


static RM 
rmPrint; 


Supported On: 

PM 


Nested Type Definitions 

Printlndicator 

Printlndicator { 

sourcePrints = 0x0001, 
targetPrints = 0x0002, 
abortPrint = 0x0003 
}; 


Enumeration of the possible print indicator values: 

sourcePrints 

The source accepts responsibility for the operation. 

targetPrints 

The target accepts responsibility for the operation. 

abortPrint 

The entire operation is aborted. 


DraglmageStyle 

DraglmageStyle { 
stack3AndFade, 
al1 Stacked, 
systemlmages 
}; 


Enumeration of the possible styles used when displaying the drag images: 

stack3AndFade 

Shows the first three images provided in the drag items and then shows a 
special icon that looks like the rest of the images fading out. This is optimal 
when the user can drag more than three items. If no images are specified, 
system images are used. 

allStacked 

Shows each image provided in each drag item. If no images are specified, 
system images are used. 
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systemlmages 

If one item is dragged, the ISystemPointerHandle::singleFile icon is used. For 
more than one item, the ISystemPointerHandle::multipleFile icon is used. Any 
images supplied with drag items are ignored. 

Source { 

pointingDevice, 
keyboard 
}; 


Enumeration of the possible drag begin sources: 

pointingDevice 

The drag began via a mouse. 

keyboard 

The drag began via the keyboard. 


DropStyle { 

notContainer = 0x0000, dropAtPosition = 0x0001, alignVertical = 0x0002, 
alignFlow = 0x0004, flowBeside = 0x0008 

}; 


Enumeration of the possible styles used when dropping items on a container: 

notContainer 

The target is not a container. 

dropAtPosition 

Drops items at the position they were in the list. 

align Vertical 

Aligns the items along the vertical axis. 

alignFlow 

Aligns the items along the window. 

flowBeside 

Aligns the items beside the window. 

Discardlndicator 

Discardlndicator { 

sourceDiscards = 0x0001, 
targetDiscards = 0x0002, 
abortDiscard = 0x0003 
}; 


Enumeration of the possible discard indicator values: 


© IBM Corp. 1992, 1995 


IDM 363 



IDM 


sourceDiscards 

The source accepts responsibility for the operation. 

targetDiscards 

The target accepts responsibility for the operation. 

abortDiscard 

The entire operation is aborted. 


RenderCompletion 

RenderCompletion { 

targetSuccessful = 0x0001, targetFailed = 0x0002, 
retry = 0x0008, renderOk = 0x0010, 

fail = 0x0020 

}; 


Enumeration of the possible render completion values: 

targetSuccessful 

The target has successfully completed the rendering operation. 

targetFailed 

The target failed to complete the rendering operation. 

retry 

The source has completed the rendering operation and will allow the target to 
retry its part of the operation if it fails. 

renderOk 

The source has completed the rendering operation. 

fail 

The source failed to complete the rendering operation. 


Droplndicator 

Droplndicator { 
notOk = 0x0000, 
ok = 0x0001, 

operationNotOk = 0x0002, 
neverOk = 0x0003 
}; 


Enumeration of the possible drop indicator values: 

ok 

The drop is allowed. 

notOk 

The drop is not allowed at this location. 
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operationNotOk 

The operation or operations are not allowed. 

neverOk 

The drop is not allowed on this window. 


typedef const char * Type; 

Enumeration of the possible drag item types used for items in a direct manipulation: 

any 

Any type. 

binary 

Generic binary item type. 

binaryData 

Binary data item type. 

bitmap 

Bitmap item type. 

container 

Container item type. 

containerObject 

Container object item type. 

file 

File item type. 

icon 

Icon item type. 

menultem 

Menu item drag item type. 

plainText 

Plain text drag item type. 

text 

Generic text drag item type. 

tooIBarButton 

Tool bar button drag item type. 

unknown 

Unknown drag item type. 


typedef const char * RF; 
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Enumeration of the possible rendering formats used for items in a direct 
manipulation: 

rfUnknown 

Unknown rendering format. 

rflext 

Text rendering mechanism. (Used if text length <= 255 and text does not 
contain embedded NULL characters) 

rfProcess 

Process rendering format. ("="+PID suffix added for interprocess rendering) 

rfSharedMem 

Shared memory rendering format. 

rfObject 

Workplace Shell object rendering format. 

rfAny 

Any rendering format. 


typedef const char * RM; 

Enumeration of the possible rendering mechanisms used for items in a direct 
manipulation: 

rmFile 

Lile rendering mechanism. 

rmObject 

Workplace Shell object rendering mechanism. 

rmDiscard 

Discard rendering mechanism. 

rmPrint 

Print rendering mechanism. 

rmLibrary 

User Interface Class Library rendering mechanism. 

rmAny 

Any rendering mechanism. 
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IDMCnrltem 


IBase 

IVBase 

IRefCounted 

IDMItem 

IDMCnrltem 


_.None. 

—idmcnrit.hpp 


Member 

Page 

Member 

Page 

Constructor 

368 

sourceContainer 

369 

containerld 

369 

targetDrop 

368 
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369 

'IDMCnrltem 

368 


Containers create objects of the IDMCnrltem class when: 

• A direct manipulation begins in a source container. 

• A container object is dragged over a potential target container during a direct 
manipulation. 

In addition to attributes inherited from IDMItem, objects of this class have a pointer 
to the source or target container over which this item is being dragged. 

This class provides virtual functions that implement direct manipulation support for 
the container. You can create derived item classes to support the direct manipulation 
of container objects. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 
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IDMCnrltem 

[] IDMCnrItem( IContainerControl* container. Supported On: 

IContainerObject* object, PM 

IDMSourceOperation* sourceOperation, 
const ISize& imageOffset); 

Use this constructor to construct items for the source of a direct manipulation. It 
accepts the pointers to a container control and object, a pointer to the drag source 
operation, and the offset of the drag image. 

2 IDMCnrItem( const IDMItem::Handle& dragltem); Supported On: 

PM 

Use this constructor to construct items for the target of a direct manipulation. It 
accepts a handle to a generic drag item. 

The generic drag item is passed to IDMItemProviderFor::provideTargetItemFor of the 
target container’s drag item provider. IDMItemProviderFor::provideTargetItemFor 
uses the generic drag item to construct a container drag item by calling this 
constructor. 

"IDMCnrltem 


virtual 

"TDMCnrltemO; 


Supported On: 

PM 


Drop Processing 

Use these members during the drop operation of a direct manipulation. 

_Use this function to process the drop of drag items that represent container objects. 
This function adds the object into the target container. Derived classes should 
override this function to insert the associated container object into the target 
container. 

Note: If multiple items are dropped, this function is called once for each item. 

virtual Boolean Supported On: 

targetDrop( IDMTargetDropEvent& event); PM 


Exceptions 

IlnvalidRequest The drop cannot be completed. A source object must exist for this 

operation. 
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Source Items 

Use these members to access and manipulate source items involved in a direct manipulation. 
-.Returns the source container’s ID. 


virtual unsigned long 
containerId() const; 


Supported On: 

PM 


generateSou rceltems 

Use this function to generate drag items that represent container objects selected in 
the source container. 


static Boolean 

generateSourceltems( IDMSourceOperation* sourceOperation); 


Supported On: 

PM 


sourceContainer 

Returns a pointer to the source container. 


virtual IContainerControl* 
sourceContainer() const; 


Supported On: 

PM 


Inherited Public Functions 


IDMItem 

addRMF 

nativeRF 

setRequiresPreparation 

addType 

nativeRM 

setRMFs 

appendRMF 

nativeRMF 

setSelectedRMF 

attributes 

object 

setSourceName 

canBeCopied 

operator = 

setS ource Windo wHandle 

canBeLinked 

removeRMF 

setTargetName 

canBeMoved 

removeType 

setTrueType 

compressedRMF s 

Tenderer 

setTypes 

containerName 

requiresPreparation 

sourceDiscard 

contents 

rfF orThisProcess 

sourceEnd 

contentsSize 

rfFrom 

sourceltemFor 

deleteRMF 

rinfFi'om 

sourceName 

dropStatus 

rmFrom 

sourceOperation 

enableCopy 

rmfs 

sourcePrepare 
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IDMItem 

enableLink 

rmfsFrom 

sourcePrint 

enableMove 

selectedRMF 

sourceRender 

generateSourceltems 

setContainer 

source Window 

haslmage 

setContainerN ame 

source WindowHandle 

hasType 

setContents 

supportedOperations 

image 

setDropStatus 

supportedOperationsFor 

imageOffset 

setGroup 

supportsRMF 

isContainer 

setlmage 

targetDrop 

isGroup 

setNativeRMF 

targetEnd 

isOnRemovableMedia 

setObject 

targetName 

isOpen 

setOnRemovableMedia 

targetOperation 

isReference 

setOpen 

tokenForWPSObject 

isTargetTheSource 

setReference 

trueType 

matchingRMFs 

setRenderer 

types 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDMItem 

generateSourceName 
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Inherited Public Data 


IDMItem 

container 

linkable 

open 

copyable 

moveable 

prepare 

group 

none 

reference 


Inherited Protected Data 


IDMItem 

strContents 




IBase 

recoverable 

unrecoverable 
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IDMEFItem 


IBase 

IVBase 

IRefCounted 

IDMItem 

IDMEFItem 


_.None. 

—idmefit.hpp 


Member 

Page 

Member 

Page 

Constructor 

373 

targetDrop 

373 

generateSourceltems 

374 

'IDMEFItem 

373 

object 

374 




Entry fields create objects of the IDMEFItem class when: 

• A direct manipulation commences in a source entry field. 

• A text object is dropped on a target entry field during a drag operation. 

Objects of this class have the following attributes in addition to those inherited from 
its base class: 

• The association with a source or target drag operation object. 

• The association with an IDM::rmLibrary rendering mechanism and an 
IDM::rfProcess rendering format. If the text size is <= 255 bytes and the 
IDM::rmFile rendering mechanism is not being used, the IDM::rfText rendering 
format is added. Otherwise, the IDM::rfSharedMem rendering format is used 
instead. 

This class provides virtual functions that implement direct manipulation support for 
the entry field. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMEFItem 

Q IDMEFItem( IDMSourceOperation* sourceOperation); Supported On: 

PM 

Use this constructor to construct items for the source of a direct manipulation. It 
accepts a pointer to the drag source operation. 

@ IDMEFItem( const IDMItem: :Handle& dragltem); Supported On: 

PM 

Use this constructor to construct items for the target of a direct manipulation. It 
accepts a handle to a generic drag item. 

The generic drag item is passed to IDMItemProviderFor::provideTargetItemFor of the 
target entry field's drag item provider. IDMItemProviderFor::provideTargetItemFor 
uses the generic drag item to construct an entry field drag item by calling this 
constructor. 

IDMEFItem 

virtual 
"IDMEFItemO; 

Drop Processing 

Use these members during the drop operation of a direct manipulation. 

_Use this function to process the drop of a drag item that represents a text object. 

This function sets the object into the target entry field. Derived classes should 
override this function to insert the associated text object into the target entry field 
when the default processing cannot be used. 

virtual Boolean Supported On: 

targetDrop( IDMTargetDropEvent& targetDropEvent); PM 


Supported On: 

PM 
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Source Items 

Use these members to access and manipulate source items involved in a direct manipulation. 


generateSourceltems 

Use this function to generate a drag item that represents a text object. The text object 
can be the entire contents of the source entry field, or a selected portion. 

static Boolean Supported On: 

generateSourceltems( IDMSourceOperation* sourceOperation); PM 

Returns a pointer to the contents of the IString that contains the text being 
manipulated. The pointer can be cast to the type char * to directly access the text. 

virtual void* Supported On: 

object() const; PM 


Inherited Public Functions 


IDMItem 

addRMF 

nativeRF 

setRequiresPreparation 

addType 

nativeRM 

setRMFs 

appendRMF 

nativeRMF 

setSelectedRMF 

attributes 

object 

setSourceName 

canBeCopied 

operator = 

setSourceWindowHandle 

canBeLinked 

removeRMF 

setTargetName 

canBeMoved 

removeType 

setTrueType 

compressedRMF s 

Tenderer 

setTypes 

containerName 

requiresPreparation 

sourceDiscard 

contents 

rfF orThisProcess 

sourceEnd 

contentsSize 

rfFrom 

sourceltemFor 

deleteRMF 

rrnIFrom 

sourceName 

dropStatus 

rmFrom 

sourceOperation 

enableCopy 

rmfs 

sourcePrepare 

enableLink 

rmfsFrom 

sourcePrint 

enableMove 

selectedRMF 

sourceRender 

generateSourceltems 

setContainer 

source Window 

haslmage 

setContainerN ame 

source WindowHandle 
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IDMItem 

hasType 

setContents 

supportedOperations 

image 

setDropStatus 

supportedOperationsFor 

imageOffset 

setGroup 

supportsRMF 

isContainer 

setlmage 

targetDrop 

isGroup 

setNativeRMF 

targetEnd 

isOnRemovableMedia 

setObject 

targetName 

isOpen 

setOnRemovableMedia 

targetOperation 

isReference 

setOpen 

tokenForWPSObject 

isTargetTheSource 

setReference 

trueType 

matchingRMFs 

setRenderer 

types 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDMItem 

generate S ourceN ame 




Inherited Public Data 


IDMItem 

container 

linkable 

open 

copyable 

moveable 

prepare 

group 

none 

reference 
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IBase 

IVBase 

IEvent 

IDMEvent 


IDMSourceBeginEvent 

IDMSourceDiscardEvent 

IDMSourceEndEvent 

IDMSourcePrintEvent 


IDMSourceRenderEvent 

IDMTargetEndEvent 

IDMTargetEvent 

IDMTargetHelpEvent 


_ idmevent.hpp 

Member Page 

Constructor 377 

'IDMEvent 378 


IDMEvent is the base class for all direct manipulation event classes. 

Note: Neither the User Interface Class Library nor Presentation Manager provide 
default processing for drag events, besides the library-provided 
implementation of virtual functions. If you provide your own implementation 
of these virtual functions, do not assume returning a value of false will cause 
correct processing to be done for you. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

..Construct objects of this class from a generic IEvent (Vol. II). 

IDMEvent( const IEvent& event); Supported On: 

PM 
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"IDMEvent 


virtual 
"IDMEvent(); 


Supported On: 

PM 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMHandler 


IBase 

IVBase 

IHandler 

IDMHandler 


IDMSourceHandler 

IDMTargetHandler 


„idmhndlr.hpp 


Member Page 

Constructor 384 

addRenderer 385 

defaultSourceHandler 379 

defaultTargetHandler 380 

enableDragDropFor 381 

enableDragFrom 381 

enableDropOn 382 

isContainerControl 384 

numberOfRenderers 385 


Member 

Page 

removeRenderer 

386 

Tenderer 

386 

replaceRenderer 

386 

setDefaultSourceHandler 

380 

setDefaultT argetHandler 

380 

setltemProvider 

384 

setRenderer 

386 

'IDMHandler 

384 


The IDMHandler class is the base class for the source handler class, 
IDMSourceHandler, and the target handler class, IDMTargetHandler. 

This base class provides static functions to enable you to add drag and drop support 
to your application's windows and controls. 


Public Functions 
Default Handlers 

Use these static members to get and set the default source and target handlers used by the 
various enabling functions. 


defaultSourceHandler 

Returns the default source handler. 
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Note: The handler returned by this function may have been, or will be, attached to 
any window for which any of the enabling functions (enableDragFrom, 
enableDropOn, or enableDragDropFor) has been called. Any changes you make to 
this handler, such as adding tenderers, removing tenderers, or changing the Tenderers 
will affect all of these windows. 

static IDMSourceHandl er& 
defaultSourceHandler(); 

defauItTargetHandler 

Returns the default target handler. 

Note: The handler returned by this function may have been, or will be, attached to 
any window for which any of the enabling functions (enableDragFrom, 
enableDropOn, or enableDragDropFor) has been called. Any changes you make to 
this handler, such as adding tenderers, removing tenderers, or changing the Tenderers 
will affect all of these windows. 

static IDMTargetHandler& 
defaul tTargetHandler(); 

setDefaultSourceHandler 

Sets the default source handler to the specified handler. This handler will be attached 
to windows on subsequent calls to IDMHandler::enableDragFrom or 
IDMHandler:: enableDragDropFor. 

static void Supported On: 

setDefaultSourceHandler( IDMSourceHandler& source); PM 

setDefauItTargetHandler 

Sets the default target handler to the specified handler. This handler will be attached 
to windows on subsequent calls to IDMHandler::enableDropOn or 
IDMHandler:: enableDragDropFor. 

static void Supported On: 

setDefaul tTargetHandl er( IDMTargetHandler& target); PM 


Supported On: 

PM 


Supported On: 

PM 


Enabling Direct Manipulation 

Use these static members to provide a simple means of enabling drag and drop for application 
windows and controls. 
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enableDragDropFor 

Attaches the default source and target handlers to the specified window and the 
default source and target Tenderers to their respective handlers. 

[] static void Supported On: 

enabl eDragDropFor( IToolBarButton* tool BarButton); PM 

A drag item provider is attached to the tool bar button, by default, which provides 
default direct manipulation support for it. If you want specialized direct manipulation 
support for the tool bar button, you must attach your own drag item providers. 

^ static void Supported On: 

enableDragDropFor( IWindow* window); PM 

You must attach a drag item provider for any types of windows or controls that are 
not supported by the User Interface Class Library to enable them to support direct 
manipulation. 

g static void Supported On: 

enableDragDropFor( IEntryField* entryField); PM 

A drag item provider is attached to the entry field, by default, which provides default 
direct manipulation support for it. If you want specialized direct manipulation 
support for the entry field, you must attach your own drag item providers. 

E static void Supported On: 

enableDragDropFor( IMul ti LineEdit* mle); PM 

A drag item provider is attached to the multi-line edit (MLE), by default, which 
provides default direct manipulation support for it. If you want specialized direct 
manipulation support for the MLE, you must attach your own drag item providers. 


§ static void Supported On: 

enableDragDropFor( IContainerControl* container); PM 

A drag item provider is attached to the container, by default, which provides default 
direct manipulation support for it. If you want specialized direct manipulation 
support for the container, you must attach your own drag item providers. 

enableDragFrom 

Attaches the default source handler to the specified window and the default source 
Tenderer to the handler. 


| static void 

enableDragFrom( IEntryField* entryField); 


Supported On: 

PM 
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A drag item provider is attached to the entry field, by default, which provides default 
direct manipulation support for it. If you want specialized direct manipulation 
support for the entry field, you must attach your own drag item providers. 

5 static void Supported On: 

enableDragFrom( IWindow* window); PM 

You must attach a drag item provider for any types of windows or controls that are 
not supported by the User Interface Class Library to enable them to support direct 
manipulation. 

0 static void Supported On: 

enabl eDragFrom( IMul ti LineEdi t* ml e); PM 

A drag item provider is attached to the multi-line edit (MLE), by default, which 
provides default direct manipulation support for it. If you want specialized direct 
manipulation support for the MLE, you must attach your own drag item providers. 

2 static void Supported On: 

enableDragFrom( IContainerControl* container); PM 

A drag item provider is attached to the container, by default, which provides default 
direct manipulation support for it. If you want specialized direct manipulation 
support for the container, you must attach your own drag item providers. 


@ static void Supported On: 

enabl eDragFrom( IMenuBar* menuBar); PM 

No default source handler and no drag item provider is attached to the menu bar. 

The submenus of the menu bar are iterated, and IDMHandler: :enableDragFrom is 
called for each one. 


2 static void Supported On: 

enableDragFrom( ISubmenu* submenu); PM 

A drag item provider is attached to the submenu by default, which provides default 
direct manipulation support for it. If you want specialized direct manipulation 
support for the submenu, you must attach your own drag item providers. 


enableDropOn 

Attaches the default target handler to the specified window and the default target 
Tenderer to the handler. 

[j static void Supported On: 

enableDropOn( IToolBar* toolBar); PM 
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A drag item provider is attached to the tool bar, by default, which provides default 
direct manipulation support for it. If you want specialized direct manipulation 
support for the tool bar, you must attach your own drag item providers. 

^ static void Supported On: 

enableDropOn( IWindow* window); PM 

You must attach a drag item provider for any types of windows or controls that are 
not supported by the User Interface Class Library to enable them to support direct 
manipulation. 

^ static void Supported On: 

enableDropOn( IEntryField* entryField); PM 

A drag item provider is attached to the entry field, by default, which provides default 
direct manipulation support for it. If you want specialized direct manipulation 
support for the entry field, you must attach your own drag item providers. 

0 static void Supported On: 

enableDropOn( I Mu 1 ti Li neEdi t* ml e); PM 

A drag item provider is attached to the multi-line edit (MLE), by default, which 
provides default direct manipulation support for it. If you want specialized direct 
manipulation support for the MLE, you must attach your own drag item providers. 


§ static void Supported On: 

enableDropOn( IContainerControl* container); PM 

A drag item provider is attached to the container, by default, which provides default 
direct manipulation support for it. If you want specialized direct manipulation 
support for the container, you must attach your own drag item providers. 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. This class can only be used as the base 
class for concrete-derived classes, such as IDMSourceHandler and IDMTargetHandler. 

_ The default constructor takes no arguments. 

IDMHandl er(); Supported On: 

PM 


"IDMHandler 


virtual Supported On: 

''IDMHandl er(); PM 


Handler Processing 

Handler-processing members query information about the windows that the handler is attached to. 


isContainerControl 

Returns true if the window is a container control. 


Bool ean Supported On: 

isContainerControl ( const IWindow* window) const; PM 


Item Providers 

These static members set a default item provider for the argument window. 


setltemProvider 

Sets the default item provider. 


Supported On: 

PM 


| static void 

setltemProvider( IMultiLineEdit* mle); 
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Sets the default item provider for the multi-line edit. 


§ static void Supported On: 

setItemProvider( IEntryField* entryField); PM 

Sets the default item provider for the entry field. 

0 static void Supported On: 

setltemProviderj IContainerControl* container); PM 

Sets the default item provider for the container. 


0 static void 

setltemProviderj ISubmenu* submenu); 

Sets the default item provider for the submenu. 


@ static void Supported On: 

setItemProvider( IToolBar* tool Bar); PM 

Sets the default item provider for the tool bar. 


Supported On: 

PM 


E 


Rendering 

These members provide a means of accessing the base IDMRenderer objects involved in the 
direct manipulation described by objects of this class. These objects are used to handle the 
rendering of dragged objects that are compatible with the supported rendering mechanisms and 
formats (RMFs). 

_ Adds a specified Tenderer to this handler. The Tenderer is added to the end of the 
Tenderer collection. 

Note: Renderers are maintained by positions, which are 1-based. 


static void Supported On: 

setltemProvi der( IToolBarButton* tool Bar); PM 

Sets the default item provider for the tool bar button. 


virtual IDMHandler& 

addRenderer( const IDMRenderer& newRenderer); 


Supported On: 

PM 


numberOfRenderers 

Returns the number of renderers currently in the Tenderer collection. 
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virtual unsigned 
numberOfRenderers(); 


Supported On: 

PM 


removeRenderer 

Removes the specified tenderer from this handler. 

Note: Renderers are maintained by positions, which are 1-based. 


[j virtual IDMHandler& Supported On: 

removeRenderer( const IDMRenderer& rendererToRemove); PM 

§ virtual IDMHandler& Supported On: 

removeRenderer( unsigned position); PM 

Returns the Tenderer at the given position. 

Note: Renderers are maintained by positions, which are 1-based. 


virtual IDMRenderer* 
renderer( unsigned position); 


Supported On: 

PM 


replaceRenderer 

Replaces a Tenderer with another specified tenderer. 

Note: Renderers are maintained by positions, which are 1-based. 


virtual IDMHandler& 
replaceRenderer( unsigned position, 

const IDMRenderer& replacement); 


Supported On: 

PM 


_Sets the Tenderer for this handler. Removes any pre-existing renderers. 


virtual IDMHandler& 

setRenderer( const IDMRenderer& newRenderer); 


Supported On: 

PM 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMImage 


IBase 

IVBase 

IDMImage 


_.None. 


—idmimage.hpp 


Member 

Page 

Member 

Page 

Constructor 

389 

setBitmap 

391 

bitmap 

390 

setDefaultStyle 

393 

bmp 

393 

setNumberOfPoints 

391 

classDefaultStyle 

393 

setPointArray 

391 

closed 

394 

setPointer 

392 

defaultStyle 

393 

setPointerOffset 

392 

noStyle 

394 

setStretchSize 

392 

numberOfPoints 

391 

setStyle 

392 

operator = 

390 

stretch 

394 

pointArray 

391 

stretchSize 

392 

pointer 

391 

style 

392 

pointerOffset 

391 

transparent 

394 

polygon 

394 

'IDMImage 

390 

Ptr 

394 




The IDMImage class is the base class for the direct manipulation drag image classes. 
It provides the support required to represent the image of IDMItem objects that are 
dragged during direct manipulation. An image can be an icon or bitmap handle that 
is drawn while the drag operation is in progress. The image represents the objects 
being dragged. 

Create objects of this class to provide an image to be displayed for each IDMItem 
object being dragged. As you create each IDMItem object you can create an object 
of this class and attach it to the object so that the proper image representation can be 
supplied during the direct manipulation operation. If you do not attach this class to 
IDMItem objects, default system icons are used for the image. 

Objects of this class have the following attributes in addition to those inherited from 
its base class: 

• An image handle 
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• A stretch size for the image 

• Styles that determine the type and shape of the image 

• The offset of the image from the pointing device 

• The number of points in a point array, if certain styles are set 

Note: If you use IDM::systemImages for the images, you do not need to create 
objects of this class. IDM::systemImages generates and uses system images and 
causes images attached to the items to be ignored. 


Public Functions 
Constructors 

You can construct, copy, assign, and destruct objects of this class. 


IDMImage 

Q IDMImage( unsigned long arrayOfPoints [ ], Supported On: 

const unsigned long numberOfPoints, PM 

const ISize& pointerOffset = ISize (0,0), 
const Style& style = defaultStyle ( )); 

Use this version of the constructor to create objects of this class if you want to draw 
a polygon as an image. Specify the array of points for the polygon in arrayOfPoints , 
and the number of points to draw in numberOfPoints. 

g IDMImage(); Supported On: 

PM 


This is the default constructor. 


£j IDMImage( const IResourceId& resourceld. Supported On: 

Boolean iconResource = true, PM 

const ISize& pointerOffset = ISize (0,0), 
const ISize& stretchSize = ISize ( 0 , 0 ), 
const Style& style = defaultStyle ( )); 

Use this version of the constructor to create objects of this class if you want to use a 
bitmap or an icon as the drag image and the bitmap or icon is not already loaded. 

Use resourceld to specify the resource identifier for the bitmap or icon to load from a 
resource, and use iconResource to specify if the resource is a bitmap or icon. 
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E 


IDMImage( const 
const 
const 
const 


IPointerHandle& icon, 

ISize& pointerOffset = ISize (0 , 0 ), 
I Size& stretchSize = ISize (0,0), 
Style& style = defaultStyle ( )); 


Supported On: 

PM 


Use this version of the constructor to create objects of this class if you want to use a 
pointer as the drag image and the pointer is already loaded from a resource. 


s 


IDMImage( const 
const 
const 
const 


IBitmapHandle& bitmap, 

I Size& pointerOffset = ISize (0 , 0 ), 
I Size& stretchSize = ISize (0,0), 
Style& style = defaultStyle ( )); 


Supported On: 

PM 


Use this version of the constructor to create objects of this class if you want to use a 
bitmap as the drag image and the bitmap is already loaded from a resource. 


@ IDMImage( const IDMImage& image); 


Supported On: 

PM 


Use this version of the constructor, a copy constructor, to make a copy of the drag 
image object. 


_.Use this operator to assign an IDMImage object to another IDMImage object. 


IDMImage& Supported On: 

operator =( const IDMImage& image); PM 


IDMImage 

This destructor deletes the array of points if it exists. 


virtual 

"TDMImageO ; 


Supported On: 

PM 


Image Processing 

Use these members to set and query attributes of this class. These attributes include the 
following: 

• Bitmaps 

• Icons 

• Polygons 

• Style 

-Returns the handle to the bitmap image. If the image is not a bitmap, 0 is returned. 
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IBi tmapHandle 
bitmap() const; 


Supported On: 

PM 


numberOfPoints 

Returns the number of array points that constitute the polygon image. 


unsigned long 
numberOfPoints(); 


Supported On: 

PM 


-Returns a pointer to the array of points, if the image style is set to 
IDMImage::polygon. If the image style is not IDMImage: ipolygon, returns 0. 


unsigned long* 
pointArray(); 

.Returns the handle to the pointer image. 


Supported On: 

PM 


IPointerHandle 
pointer() const; 

— Returns the offset of the image from the pointing device. 


Supported On: 

PM 


ISi ze 

pointerOffset() const; 

-Sets the handle to the bitmap image. 


Supported On: 

PM 


IDMImage& 

setBitmap( const IBitmapHandle& bitmaplmage); 


Supported On: 

PM 


setNumberOfPoints 

Sets the number of array points that constitute the polygon image. 

IDMImage& Supported On: 

setNumberOfPoints( unsigned long points); PM 


setPointArray 

Sets the array of points for drawing the polygon image and adds IDMImage "polygon 
to the image style. 


Q IDMImage& 

setPointArray( unsigned long arrayOfPoints [ ], 
unsigned long numberOfPoints); 


Supported On: 

PM 
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Sets the array of points for drawing a polygon image. If numberOfPoints is a value 
greater than 0, the current array is deleted and the new array is set. If 
numberOfPoints is 0, the current array is deleted. 

_Sets the handle to the pointer image. 


IDMImage& 

setPointer( const IPointerHandle& pointerlmage); 


Supported On: 

PM 


setPointerOffset 

Sets the offset of the image from the pointing device. 


IDMImage& 

setPointerOffset( const ISize& pointerOffset); 


Supported On: 

PM 


setStretchSize 

Sets the size of the bitmap or icon image drawn during direct manipulation. This 
only applies if the image is a bitmap or icon. 

Note: This function is often required because the bitmaps are typically much larger 
than the user would like to see during a direct manipulation. 

IDMImage& 

setStretchSize( const ISize& stretchSize); 

_Sets the styles that describe the image. 

IDMImage& Supported On: 

setStyle( const Style& style); PM 

-.Returns the size of the stretched image. The bitmap or icon is drawn with this size 
during direct manipulation. 

ISize 

stretchSize() const; 

Returns the styles that describe the image. 

Style Supported On: 

style(); PM 


Supported On: 

PM 


Supported On: 

PM 


392 


Open Class Library Reference 



IDMImage 


Styles 

Use these members to set and query the styles for this class. 

_ Returns the current default style. This is the same as IDMImage: :classDefaultStyle 
unless IDMImage::setDefaultStyle has been called. 

static Style Supported On: 

defaultStyle(); PM 


setDefaultStyle 

Sets the default style for all subsequent drag images. 


static void 

setDefaaltStyle( const Style& style); 

Supported On: 

PM 

Inherited Public Functions 

IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 
Styles 

Use these members to set and query the styles for this class. 

The image is an IBitmapHandle (Vol. II). 

static const Style Supported On: 

bmp; PM 

classDefaultStyle 

The original default style for the IDMImage class, which is IDMImage: :noStyle. 
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static const Style 
classDefaultStyl e; 


Supported On: 

PM 


.If the image is a polygon, a closed polygon is formed by moving the current position 
to the last point in the array of points before drawing. 


static const Style 
closed; 

_Sets all of the styles off. This is the default style setting. 


Supported On: 

PM 


static const Style 
noStyle; 


Supported On: 

PM 


_The image is a pointer to an array of points that will be connected to form a 
polygon. The first point of the array should be (0,0), and the other points should be 
placed relative to this position. 


static const Style 
polygon; 

The image is an IPointerHandle (Vol. II). 


Supported On: 

PM 


static const Style 
ptr; 


Supported On: 

PM 


If the image is an IPointerHandle (Vol. II) or an IBitmapHandle (Vol. II), the image 
is stretched to the dimensions specified by IDMImage: :stretchSize. 


static const Style 
stretch; 


Supported On: 

PM 


_If the image is an IPointerHandle (Vol. II), an outline of the image is generated and 
displayed instead of the original image. 


static const Style 
transparent; 


Supported On: 

PM 


Inherited Protected Data 
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Nested Classes 

IDMImage contains the following nested classes: 
IDMImage::Style (see page 396) 
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IBase 

IBitFlag 

IDMImage: :Style 


_.None. 

_idmimage.hpp 

The IDMImage::Style class is a nested class that provides static members of the 
IDMImage class that define the set of valid image styles. 

ptr 

The image is an IPointerHandle. 

bmp 

The image is an IBitmapHandle. 

polygon 

The image is a pointer to an array of points that connect to form a polygon. 
The first point of the array should be (0,0) and the other points should be 
placed relative to this position. 

stretch 

If the image is an IPointerHandle or an IBitmapHandle, the image is stretched 
to the dimensions specified by stretchSize. 

transparent 

If the image is an IPointerHandle, an outline of the image is generated and 
displayed instead of the original image. 

closed 

If the image is a polygon, a closed polygon is formed by moving the current 
position to the last point in the array of points before drawing. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

IRefCounted 

IDMItem 


IDMCnrltem 

IDMMLEItem 

IDMEFItem 

IDMTBaiButtonltem 

IDMMenuItem 

IDMToolBarltem 


_ddmitem.hpp 




Member 

Page 

Member 

Page 

Constructor 

400 

isTargetTheSource 

411 

addRMF 

413 

linkable 

420 

addType 

410 

matchingRMFs 

412 

appendRMF 

411 

moveable 

420 

attributes 

404 

nativeRF 

413 

canBeCopied 

402 

nativeRM 

413 

canBeLinked 

402 

nativeRMF 

413 

canBeMoved 

402 

none 

419 

compressedRMFs 

411 

object 

409 

container 

418 

open 

419 

containerName 

405 

operator = 

401 

contents 

409 

prepare 

419 

contentsSize 

409 

reference 

419 

copyable 

419 

removableMedia 

419 

deleteRMF 

412 

removeRMF 

413 

dropStatus 

404 

removeType 

410 

enableCopy 

402 

Tenderer 

414 

enableLink 

402 

requiresPreparation 

406 

enableMove 

403 

rfForThisProcess 

412 

generateSourceltems 

415 

rfFrom 

412 

generates ourceName 

418 

rmfFrom 

412 

group 

419 

rmFrom 

412 

haslmage 

403 

rmfs 

414 

hasType 

410 

rmfsFrom 

413 

image 

403 

selectedRMF 

415 

imageOffset 

405 

setContainer 

406 

isContainer 

405 

setContainerName 

407 

isGroup 

405 

setContents 

409 

isOnRemovableMedia 

406 

setDropStatus 

404 

isOpen 

406 

setGroup 

407 

isReference 

406 
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Member 

Page 

Member 

Page 

setlmage 

403 

sourcePrepare 

416 



sourcePrint 

417 

setNativeRMF 

414 

sourceRender 

417 

setObject 

409 

sourceWindow 

408 

setOnRemovableMedia 

407 

sourceWindowHandle 

408 

setOpen 

407 

strContents 

420 

setReference 

407 

supportedOperations 

408 

setRenderer 

415 

supportedOperationsFor 

403 

setRequiresPreparation 

407 

supportsRMF 

414 

setRMFs 

414 

targetDrop 

417 

setSelectedRMF 

415 

targetEnd 

417 

setSourceName 

408 

targetName 

409 

setSourceWindowHandle 

408 

targetOperation 

404 

setTargetName 

408 

tokenForWPS Object 

411 

setTrueType 

410 

trueType 

410 

setTypes 

410 

types 

410 

sourceDiscard 

416 

unknown 

420 

sourceEnd 

416 

'IDMItem 

402 

sourceltemFor 

411 



sourceName 

408 



sourceOperation 

404 




Objects of the IDMItem class represent items being dragged or dropped during a 
direct manipulation. 

This class provides virtual functions implementing base support for direct 
manipulation item objects in the User Interface Class Library. You can create derived 
classes to support specific items, such as text item objects and container item objects. 

Objects of this class have the following attributes in addition to those inherited from 
its base class: 

• A source window handle. 

• The types of the dragged object (true and additional). 

• The rendering mechanisms and formats (RMFs) of the dragged object (native and 
additional). 

• The container name which is the source of the direct manipulation operation. 

• The source name. 

• The suggested target name. 

• The item image that visually represents the item while it is being dragged. 

• The offset from the pointing device to the origin of the image for this item. 
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• The source flags providing instructions on how to render an object, such as 
making the object copyable only, or identifying the object as a container of other 
objects. 

• The generic IString buffer contents, which hold a various assortment of bytes 
representing the object being dragged. 

IDMRenderer objects typically transfer these bytes between the source and target 
windows. The four objects involved in transferring the dragged object - source 
item, source Tenderer, target item, and target tenderer - must have the same 
format for the item contents within the context of the RMF being used to 
manipulate the object. 

For example, IDMEFItem and IDMRenderer use the item contents to hold the 
source entry field text. Derived item classes can use this attribute optionally, 
provided the tenderers they work with use the attribute in a compatible fashion. 

• The generic object pointer, which holds a pointer to an object. 

When using IDMRenderer objects, the library-defined rendering mechanism, and 
the process rendering format, the object pointed to is the object being dragged. 
Therefore, if the target window is in the same process as the source window, the 
target window can access the dragged object directly. 

As with the item contents, the source items, target items, source Tenderers and 
target Tenderers must agree on the nature of the value of this field and derived 
item classes (and Tenderer classes) can use this attribute optionally. 

• An association with a source or target drag operation object (see 
IDMSourceOperation (p. 467) or IDMTargetOperation) (p. 514). 

• Associations with a selected source or target drag Tenderer object (see 
IDMSourceRenderer (p. 479) or IDMTargetRenderer) (p. 519), which the source 
handler or target handler creates, respectively. 


Public Functions 
Constructors 

You can construct, copy, assign, and destruct objects of this class. 


IDMItem 


[J IDMItem( IDMSourceOperation* sourceOperation, Supported On: 

const IString& types, PM 

const unsigned long supportedOperations = unknown, 
const unsigned long attributes = none); 
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Use this constructor to construct items for the source of a direct manipulation. It 
accepts a pointer to the drag source operation, types, supported operations, and 
attributes. 

§ IDMItem( IDMTargetOperation* targetOperation, Supported On: 

_DRAGITEM* dragltem); PM 

The User Interface Class Library uses this constructor to construct items for the target 
of a direct manipulation. You should never call it. 

IPM The parameter, dragltem, is a pointer to the OS/2 Presentation Manager DRAGITEM 
structure. 

g IDMItem( const IDMItem& dragltem); Supported On: 

PM 

Use this constructor, a copy constructor, to make a copy of an existing IDMItem 
object. 

This constructor increments the drag operation's use count. The drag operation use 
count is used to manage the destruction of the respective source and target operation 
objects. 

0 IDMItem( const Handle& item); Supported On: 

PM 


Use this constructor to construct generic drag items for the target of a direct 
manipulation. It accepts a handle to a generic drag item. 

The generic drag item is passed to IDMItemProviderFor::provideTargetItemFor of the 
drag item provider for the derived item class. 

IDMItemProviderFor::provideTargetItemFor uses the generic drag item to construct a 
drag item for the derived item class. 

This constructor increments the drag operation's use count. The drag operation use 
count is used to manage the destruction of the respective source and target operation 
objects. 

.Overloaded definition of the assignment operation to handle assignments of drag 

items to drag items. 

This operator increments the drag operation's use count. The drag operation use 
count is used to manage the destruction of the respective source and target operation 
objects. 
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[] IDMItem& 

operator =( const IDMItem& item); 


Supported On: 

PM 


Q Handle 

operator =( const Handle& item); 


Supported On: 

PM 


"IDMItem 

This destructor decrements the drag operation's use count. The drag operation use 
count is used to manage the destruction of the respective source and target operation 
objects. 


virtual 
"I DM I tern (); 


Supported On: 

PM 


Direct Manipulation Operations 

Use these members to set and query the operations supported for a drag item object. 

-...Returns true if the dragged object can be copied. 

virtual Boolean 
canBeCopied() const; 

-.Returns true if the dragged object can be linked. 

virtual Boolean 
canBeLinked() const; 

- Returns true if the dragged object can be moved. 

virtual Boolean 
canBeMoved() const; 

-.Enables or disables the copy operation for the drag item, 
virtual IDMItem& 

enableCopy( Boolean copyable = true); 

-Enables or disables the link operation for the drag item 

virtual IDMItem& Supported On: 

enableLink( Boolean linkable = true); PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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-Enables or disables the move operation for the drag item. 

virtual IDMItem& Supported On: 

enableMove( Boolean moveable = true); PM 

supportedOperationsFor 

Returns the operations this item supports using the specified rendering mechanisms 
and formats (RMFs). This function determines what operation is performed on this 
item using the selected RMF. For example, a printer object as the target would make 
its default operation a copy rather than a move based upon the RMF of 
<IDM: :rmPrint,IDM: :rfUnknown>. 

The default implementation calls IDMItem: :supportedOperations and returns the 
result. 

virtual unsigned long Supported On: 

supportedOperationsFor( const IString& selectedRMFs) const; PM 


Drag Image Support 

Use these members to set and query the image for this drag item. 

-Returns true, if the drag item has an associated image. 

Boolean Supported On: 

haslmage() const; PM 

Returns a reference to the drag image associated with the drag item. If the drag item 
does not have a drag image associated with it, a default drag image is created, 
associated with the drag item, and returned. 

virtual IDMImage& 
image(); 

-Sets the item's drag image. 

virtual IDMItem& Supported On: 

setlmage( IDMImage& image); PM 


Supported On: 

PM 


Drag Operation 

Use these members to access the drag operations. 
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sourceOperation 

Returns a pointer to the source operation for the drag item. If the item represents the 
dropped object at the target of the direct manipulation, 0 is returned. 


virtual IDMSourceOperation* 
sourceOperation (); 


Supported On: 

PM 


targetOperation 

Returns a pointer to the target operation for the drag item. If the item represents the 
item at the source of the direct manipulation, 0 is returned. 


virtual IDMTargetOperation* 
targetOperation (); 


Supported On: 

PM 


Drop Status 

Use these members to set and query the item's drop status. The drop status determines if this 
item can be dropped on its current target. 

_ Returns the drop status for the drag item. 

Droplndicator Supported On: 

dropStatus() const; PM 


setDropStatus 

Sets the drop status for the drag item. 


IDMItem& 

setDropStatus( Droplndicator status); 


Supported On: 

PM 


Item Attributes 

Use these members to set and query attributes of an item. The attributes include the source and 
target name, source and target window, and general container information. 

_Returns the control attributes for the item. These attributes indicate the nature of the 
dragged object and are comprised of a set of flags defined by the following static 
members: 

none 

No attributes are defined. 

open 

The source object is open. 
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reference 

The source object is a reference to another object. 

group 

The source object is a group of objects. 

container 

The source object is a container of other objects. 

prepare 

The source object requires preparation before it establishes a data transfer 
conversation. 

removableMedia 

The source object is on removable media, or the source object cannot be easily 
recovered after a move operation. 

Note: These static members represent bit masks which are patterns of characters 
used to control portions of another pattern of characters. Any user-defined 
value must be greater than the removableMedia value. 

virtual unsigned long Supported On: 

attributes() const; PM 


containerName 

Returns the source container's name. If the selected RMF is 

<IDM::rmFile,IDM::rfText>, this function returns the fully qualified path name where 
the file resides. 

virtual IString Supported On: 

containerNameO const; PM 

_Returns the offset from the pointing device hot spot to the origin of the image for 
this item. 

virtual ISize 

imageOffset() const; 

- Returns true if the drag item is a container of other objects 

virtual Boolean Supported On: 

isContainer() const; PM 

-Returns true if the drag item is a group of objects. 


Supported On: 

PM 
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virtual Boolean 
isGroup() const; 


Supported On: 

PM 


isOnRemovableMedia 

Returns true if the drag item is on removable media or may not be easily recovered 
after a move operation. Examples of removable media are: 

• diskettes 

• tapes 

• writeable optical disks 

• removable disk drives 


virtual Boolean 
isOnRemovableMedia() const; 


Supported On: 

PM 


Returns true if the drag item is open. A drag item could be considered open if it 
represents: 

• A file, and the file is currently open 

• A program that is currently running 

• A device that is currently open 

You may interpret these attributes in various ways depending upon your specialized 
requirements. 


virtual Boolean 
isOpen() const; 


Supported On: 

PM 


- Returns true if the drag item is a reference to another object. A drag item could be 
considered a reference if it is an alias for another object or the original object. 


virtual Boolean 
isReference() const; 


Supported On: 

PM 


requiresPreparation 

Returns true if the source requires preparation before rendering. For example, the 
User Interface Class Library uses this attribute to implement a part of its shared 
memory RMF support. 


virtual Boolean 
requiresPreparation() const; 

_Sets or resets the container attribute. 


Supported On: 

PM 
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virtual IDMItem& Supported On: 

setContainer( Boolean container = true); PM 

setContainerName 

Sets the source container name of the item. If the selected RMF is 
<IDM::rmFile,IDM::rfText>, use this function set the fully qualified path name of the 
file. 


IDMItem& Supported On: 

setContainerName( const char* containerName); PM 

_Sets or resets the group attribute. 

virtual IDMItem& 

setGroup( Boolean group = true); 

setOnRemovableMedia 

Sets or resets the removable media attribute. For example, you can set this attribute 
to true if the object represents a file on a diskette or CD ROM. 

virtual IDMItem& Supported On: 

setOnRemovableMedia( Boolean onRemovableMedia = true); PM 

_Sets or resets the open attribute. For example, you can set this attribute to true if 
the object represents a file that is currently open. 

virtual IDMItem& Supported On: 

setOpen( Boolean open = true); PM 

_ Sets or resets the reference attribute. A drag item could be considered a reference if 
it is an alias for another object or the original object. 


Supported On: 

PM 


virtual IDMItem& 

setReference( Boolean reference = true); 


Supported On: 

PM 


setRequiresPreparation 

Sets or resets the render prepare attribute. For example, the User Interface Class 
Library uses this attribute to implement a part of its shared memory RMF support. 

virtual IDMItem& Supported On: 

setRequiresPreparation( Boolean requiresPrep = true); PM 
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setSourceName 

Sets the source object's name. If the selected RMF is <IDM::rmFile,IDM::rfText>, 
use this function set the file name. 

IDMItem& Supported On: 

setSourceName( const char* sourceName); PM 

setSourceWindowHandle 

Sets the source window handle for the drag item. 


IDMItem& Supported On: 

setSourceWindowHandle( IWindowHandle window); PM 


setTargetName 

Sets the suggested target object's name. 


IDMItem& Supported On: 

setTargetName( const char* targetName); PM 

__Returns the source object's name. If the selected RMF is 
<IDM::rmFile,IDM::rfText>, this function returns the file name. 

virtual IString Supported On: 

sourceName() const; PM 


sourceWindow 

Returns a pointer to the source window for this drag item. 


virtual IWi ndow* Supported On: 

sourceWindow() const; PM 

sourceWindowHandle 

Returns the handle of the source window for this drag item. 


virtual IWindowHandle 
sourceWindowHandle() const; 


Supported On: 

PM 


supportedOperations 

Returns the operations supported by this drag item. Possible operations are the 
following: 

• IDMItem: imoveable 
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• IDMItem::copyable 

• IDMItem::linkable 

• IDMItem: :unknown 

virtual unsigned long Supported On: 

supportedOperations() const; PM 

—Returns the suggested name the dragged object should have at the target. The target 
might use a different name, for example, if the suggested name is already in use at 
the target. 

virtual IString Supported On: 

targetName() const; PM 


Item Content 

Use these members to set and query the contents of the item involved in a direct manipulation. 
Returns the data being dragged or dropped. 


virtual IString Supported On: 

contents() const; PM 

—Returns the length of the data being dragged or dropped. 

virtual unsigned long Supported On: 

contentsSize() const; PM 

Returns the pointer to the object. 


virtual void* Supported On: 

object() const; PM 

—Sets the contents of the drag item. Derived classes can call this function to set their 
contents to the data that is appropriate for the derived class. 


virtual Boolean Supported On: 

setContents( const IString& data); PM 

_.Sets the pointer to the associated application object that is being dragged or dropped. 


virtual IDMItem& Supported On: 

setObject( void* pointerToObject); PM 
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Item Type 

Use these members to set and query the type of an item. 

-Adds one or more additional types to the drag item. This function is useful in a 
derived class constructor to add to the types supported by the base class. 


virtual IDMItem& 
addType( const char* aType); 

-Returns true if the drag item supports the specified type. 


Supported On: 

PM 


virtual Boolean 

hasType( const char* aType) const; 

- Removes the specified type from the drag item. 


Supported On: 

PM 


virtual IDMItem& 
removeType( const char* aType); 

—Sets the true type of the drag item. 


Supported On: 

PM 


virtual IDMItem& 
setTrueType( const char* aType); 


Supported On: 

PM 


Sets the types for the drag item. setTypes("") removes all of the types for this item. 


virtual IDMItem& 
setTypes( const char* types); 


Supported On: 

PM 


-Returns the true type of the drag item. For example, if the object is a text file, the 
type is !DM::plainText. If the file is an icon, the type is IDM::icon. 


virtual IString 
trueType() const; 


Supported On: 

PM 


Returns all types previously set for the drag item. Individual types are separated by 
a comma. See IDMCOMM.HPP for the available types. 


virtual IString 
types() const; 


Supported On: 

PM 


Item Utilities 

Use these members to provide utility services used to implement this class. 
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isTargetTheSource 

Determines if the source and target are the same window. 

Boolean Supported On: 

isTargetTheSource() const; PM 


sourceltemFor 

Retrieves the source item handle based upon the target item if and only if the 
application is in the same process, and the specified item is a target item. Otherwise, 
0 is returned. 


static Handle 

source!temFor( const Handle& targetltem); 


Supported On: 

PM 


Exceptions 

IAccessError The source item handle could not be retrieved. The query of the process 

and thread identifier failed. The window handle may have been invalid. 


tokenForWPSObject 

Returns the token for the Workplace Shell object that can be passed to the 
OBJECT_FOR_PREC macro that returns a WPObject pointer. 

Note: The application using the token must be shell enabled or 
OBJECT_FOR_PREC will trap. 

unsigned long Supported On: 

tokenForWPSObject() const; PM 


Rendering Mechanism and Format Utilities 

Use these static members to create and query the rendering mechanism and format (RMF) for a 
drag item. 

_ Appends another rmf to an rmf string, separated by a comma, if required. 


static void 

appendRMF( IString& rmfs, 

const IString& rmf); 


Supported On: 

PM 


compressedRMFs 

Returns a compressed version of the argument rmfs string with all possible cross 
products converted to cross-product form. 
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static IString 

compressedRMFs( const IString& rmfs); 
--Deletes a particular rmf from an rmf string. 


Supported On: 

PM 


static void 

deleteRMF( IString& rmfs, 

const IString& rmf); 


Supported On: 

PM 


matchingRMFs 

Returns the intersection of the two rmf strings. An optional argument indicates that 
only the first matching rmf is required. 


static IString Supported On: 

matchingRMFs( const IString& rmfsl, PM 

const IString& rmfs2. 

Boolean firstOnly = false); 


rfForThisProcess 

Returns DRF_PROCESS=pid, where pid is the ASCII representation of the given 
numeric value. 


static IString Supported On: 

rfForThisProcess (); PM 

Returns the rendering format from a rendering mechanism and format (RMF). 


static IString Supported On: 

rfFrom( const IString& rmf); PM 

Constructs a rendering mechanism and format (RMF)-ordered pair, for example, 
"<rm,rf>". If multiple rendering mechanisms or rendering formats are included, an 
RMF cross product is constructed, for example, "(rm)x(rfl,rf2)". 


static IString 
rmfFrom( const IString& rm, 
const IString& rf); 

Returns the rendering mechanism from the specified RMF. 


Supported On: 

PM 


static IString 

rmFrom( const IString& rmf); 


Supported On: 

PM 
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Returns a full RMF string from either a single RMF string, or separate rendering 
mechanism and rendering format strings. The result will have all cross-products 
expanded. 


El 


static IString 
rmfsFrom( const 
const 


IString& rm, 
IString& rf); 


Supported On: 

PM 


§ static IString 

rmfsFrom( const IString& rmfs); 


Supported On: 

PM 


Rendering Mechanisms and Formats 

Use these members to set and query the rendering mechanism and format (RMF) for a drag item. 
_ Adds one or more RMFs to the drag item. 


Q virtual IDMItem& 

addRMF( const IString& rmf); 


g virtual IDMItem& 

addRMF( const IString& rm, 
const IString& rf); 

Returns the native rendering format of the drag item. 


Supported On: 

PM 


Supported On: 

PM 


virtual IString Supported On: 

nativeRFQ const; PM 

.Returns the native rendering mechanism of the drag item. 


virtual IString Supported On: 

nativeRM() const; PM 

.Returns the native RMF of the drag item. 


virtual IString Supported On: 

nativeRMF() const; PM 

—Removes a RMF from the drag item. 


£] virtual IDMItem& 

removeRMF( const IString& rmf); 


Supported On: 

PM 
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g virtual IDMItem& 

removeRMF( const IString& rm, 
const IString& rf); 

Returns all RMFs for the drag item. 


Supported On: 

PM 


virtual IString 
rmfs() const; 


Supported On: 

PM 


setNativeRMF 

Sets the native RMF to the specified value. 


[J virtual IDMItem& 

setNativeRMF( const IString& rm, 
const IString& rf); 


Supported On: 

PM 


Q virtual IDMItem& 

setNativeRMF( const IString& rmf); 


Supported On: 

PM 


...Sets the RMFs for the drag item. Use setRMFsf"') to remove all of the RMFs for 
the item. 


virtual IDMItem& 
setRMFs( const IString& rmfs); 


Supported On: 

PM 


supportsRMF 

Returns true if the item supports the specified RMF. 


| virtual Boolean 

supportsRMF( const IString& rmf); 


Supported On: 

PM 


3 


virtual Boolean 
supportsRMF( const 
const 


IString& rm, 
IString& rf); 


Supported On: 

PM 


Selected Renderer 

Use these members to set and query the renderer that is selected for this drag item. 
Returns the position of the selected renderer for this drag item. 
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unsigned Supported On: 

renderer() const; PM 

-.Returns the selected rendering mechanism and format (RMF) for this item in an 
ordered pair format, such as <IDM::rmLibrary,IDM::rfText>. 

IString Supported On: 

selectedRMFQ const; PM 

-.Sets the selected Tenderer for this drag item. The function's argument is the relative 
position of the specified Tenderer within the source or target handler's collection of 
Tenderers. 

Note: This function should only be called by the source or target handler. 


IDMItem& Supported On: 

setRenderer( unsigned position); PM 


setSelectedRMF 

Sets the selected rendering mechanism and format (RMF) for this drag item. The 
function's argument must be an ordered pair format, such as 
<IDM: :rmLibrary,IDM: :rfText>. 


IDMItem& Supported On: 

setSel ectedRMF( const IString& rmf); PM 


Source Items 

Use these members to access and manipulate source items involved in a direct manipulation. 


generateSou rceltems 

Use this function to generate generic drag items. This function is called by the 
implementation of IDMItemProvider::provideSourceItems in the template class 
IDMItemProviderFor (p. 426). This arrangement is designed to permit you to 
implement all of your application-specific behavior in a single class, derived from 
IDMItem or one of its derivatives, and then obtain a corresponding drag item provider 
class by creating the IDMItemProviderFor template with your derived item class. 

The default implementation of this function in this class creates generic IDMItem 
objects and adds them to the source operation. If you use the IDMItemProviderFor 
template class and you have defined a derived class, you must implement 
IDMItemugenerateSourceltems in your derived class. In your implementation, you 
should create one or more objects of your derived item class and call 
IDMOperation::addItem to add the objects to the source operation. 
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Note: Use the sourceOperation parameter to access IDMOperation::addItem. 

static Boolean Supported On: 

generateSourceltems( IDMSourceOperation* sourceOperation); PM 


Source Rendering 

Use these members when the source of a direct manipulation renders the data. 

sourceDiscard 

Use this function when an object is dropped on the shredder. Derived classes must 
override this function if the item adds the IDM::rmDiscard rendering mechanism to 
its RMFs. This function needs to perform the actual deletion of the object. The 
default implementation of this function does nothing. 

virtual Boolean Supported On: 

sourceDiscard( IDMSourceDiscardEvent& event); PM 

_.Use this function when the target has finished rendering an item and notifies the 
source that it is done. Derived classes should override this function if the source item 
requires any special cleanup before the direct manipulation ends. The default 
implementation of this function does nothing. 

virtual Boolean Supported On: 

sourceEnd( IDMSourceEndEvent& event); PM 


sourcePrepare 

Use this function when an item is dropped on a target, source rendering is used to 
render the item, and source preparation is a required part of the rendering. 

Derived classes should override this function in order to accomplish any of the 
following: 

• Creation of a secondary thread to perform the source rendering. 

• Determination of the size of a shared memory buffer. Do this if you want to 
implement your own shared memory RMF. 

• Fulfill a requirement that is not addressed by this class. 

The default implementation of this function does nothing. 

virtual Boolean Supported On: 

sourcePrepare( IDMSourcePrepareEvent& event); PM 
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_Use this function when an object is dropped on a printer. Derived classes must 
override this function if the item adds the IDMurmPrint rendering mechanism to its 
RMFs. This function must actually print the object. The default implementation of 
this function does nothing. 

virtual Boolean Supported On: 

sourcePrint( IDMSourcePrintEvent& event); PM 


sourceRender 

Use this function when an item is dropped on a target and source rendering is used to 
render the item. Derived classes should override this function if a non-default 
Tenderer is used to render the item with source rendering. The default implementation 
of this function does nothing. 

virtual Boolean Supported On: 

sourceRender( IDMSourceRenderEvent& event); PM 


Target Rendering 

Use these members when the target of a direct manipulation renders the data. 

_Use this function to process the drop of drag items on a target. Derived classes 
should override this function in order to set the data that was transferred into the 
target window. If source rendering is not used, or if source rendering is performed, 
but not in a secondary thread, target cleanup should occur in this function. The 
default implementation of this function does nothing. 

Note: If multiple items are dropped, this function is called once for each item. 

virtual Boolean Supported On: 

targetDrop( IDMTargetDropEvent& event); PM 

_Use this function when the source renders an item on a secondary thread and 
informs the target that it has finished. The call to this function is unique as the 
source actually posts an event to inform the target that it is finished; thus, this 
function is called asynchronously. 

Derived classes should override this function if the target item requires any special 
cleanup before the direct manipulation operation ends. Care must be taken to ensure 
that there is no overlap between this function or IDMItem::targetDrop, or the results 
may be unpredictable. The default implementation of this function does nothing. 

virtual Boolean Supported On: 

targetEnd( IDMTargetEndEvent& event); PM 
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Inherited Public Functions 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Source Name 

These members generate the source name when the IDM::rfText rendering format is used. 


generateSourceName 

Use this function to generate the source name for the implementation of the 
IDM::rfText rendering format. 

IString Supported On: 

generateSourceName(); PM 


Public Data 
Attribute Flags 

Use these static members to define the drag item's attribute flags. 

Note: These static members represent bit masks, patterns of characters used to control portions 
of another pattern of characters. Any user-defined values must be greater than the 
IDMItem::removableMedia value. 

The source object is a container of other objects. 

static const unsigned long Supported On: 

container; PM 
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The source object is a group of objects. 

static const unsigned long Supported On: 

group; PM 

.No attributes are defined for the source object. 


static const unsigned long 
none; 

The source object is open. 


Supported On: 

PM 


static const unsigned long Supported On: 

open; PM 

The source object requires preparation before it establishes a data transfer 
conversation. 


static const unsigned long Supported On: 

prepare; PM 

The source object is a reference to another object. 


static const unsigned long 
reference; 


Supported On: 

PM 


removableMedia 

The source object is on removable media, or the source object cannot be recovered 
after a move operation. 

static const unsigned long 
removableMedia; 

Supported Operations Flags 

Use these static members to define the supported operations of the drag item. 

Note: These static members represent bit masks , patterns of characters used to control portions 
of another pattern of characters. Any user-defined values must be greater than the 
IDMItem: dinkable value. 

_The source object that is being dragged can be copied to the specified drop location. 

static const unsigned long Supported On: 

copyabl e; PM 


Supported On: 

PM 
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The source object that is being dragged can be linked to the specified object. 

static const unsigned long Supported On: 

linkable; PM 

The source object that is being dragged can be moved to the specified drop location. 


static const unsigned long Supported On: 

moveable; PM 

.No supported drag operations are available. 


static const unsigned long 
unknown; 


Supported On: 

PM 


Protected Data 
Item Data 

These members store data for a drag item. 

_. Holds data (contents) of the drag item. This data member is protected to allow 
derived classes to either return the contents of it via the lDMItem::contents() function 
or allow the IDMItem::object() function to return a pointer to it per a derived 
implementation. 


IString 

strContents; 


Supported On: 

PM 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 



Nested Type Definitions 

typedef IReference < IDMItem > Handle; 

IDMItem::Handle provides access to the IDMItem objects associated with a direct 
manipulation. The handle manages the references to the IDMItem object and ensures 
that this object is not destructed until the direct manipulation is completed. 
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Use Handle to reference an item handle within this class and IDMItem::Handle 
externally. 

The handle provides a operator, which enables instances to be treated just like a 
pointer to an IDMItem object. 
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IDMItemProvider 


IBase 

IVBase 

IDMItemProvider 


IDMItemProviderFor 


Mdmprov.hpp 


Member 

Page 

Member 

Page 

Constructor 

423 

pro vide S ourceltems 

424 

provideEnterSupport 

423 

pro videT argetltemFor 

424 

provideHelpFor 

424 

'IDMItemProvider 

423 

provideLeaveSupport 

424 




Objects of the IDMItemProvider class provide application-specific direct manipulation 
behavior to windows and controls. The responsibilities of such objects include: 

• Providing source and target items (as described) 

• Providing help when requested while a dragged object is positioned over a 
window 

• Providing application-defined checking when a dragged object is moved over or 
exits a window; for example, to draw target emphasis 

When the source handler detects a direct manipulation is being initiated from one of 
its windows, it calls IDMItemProvider::providesourceltems. 

When items enter a potential target, generic IDMItem objects are created to represent 
them. Next, the target handler calls IDMItemProvider: :provideTargetItemFor once for 
each item to give a derived IDMItemProvider class the opportunity to replace the 
generic IDMItem objects with objects of some IDMItem derived class that provides 
application-specific behavior. 

See also the template class IDMItemProviderFor (p. 426) which can be used to 
generate a derived IDMItemProvider class for your IDMItem derived classes. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IDMItemProvider 

Use this constructor, the default constructor, to construct objects of this class. 

IDMItemProvider() ; Supported On: 

PM 

"IDMItemProvider 


virtual 

"IDMItemProviderO ; 


Supported On: 

PM 


Drag Item Support 

Use these members to provide event-specific support during a direct manipulation. 

provideEnterSupport 

Use this function to provide support for the target enter event. This function is called 
when the user moves a dragged object over the window for which the provider is 
providing direct manipulation support. 

Derived classes should override this function to accomplish any of the following: 

• Draw target emphasis on the target window 

• Validate that the object can be dropped. If it cannot be dropped, you should call 
!DMTargetEnterEvent::setDropIndicator (p. 499) for the specified 
IDMTargetEnterEvent. 

The default implementation of this function does the following: 

• For multiple-line edit (MLE) controls and the entry field, if the source and target 
windows are the same window, the drop indicator is set to IDM::neverOk. 

• For intraprocess containers, if the operation is a move, 
IContainerControl::isMoveValid (p. 187) is called. 

virtual Boolean Supported On: 

provideEnterSupport( IDMTargetEnterEvent& event); PM 
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provideHelpFor 

Use this function to provide window-specific drop help. This function is called when 
the user requests help while dragging an object over the drop target. 

Derived classes should override this function in order to provide the specific help for 
the target drop window. 

The default implementation of this function does nothing, 
virtual Boolean 

provideHelpFor( IDMTargetHelpEvent& event); 

provideLeaveSupport 

Use this function to provide support for the target leave event. This function is called 
when the user moves a dragged object off the window for which the provider is 
providing direct manipulation support. 

Derived classes should override this function in order to remove target emphasis from 
the target window. 

The default implementation of this function does nothing. 

virtual Boolean Supported On: 

provideLeaveSupport ( IDMTargetl_eaveEvent& event); PM 

provideSourceltems 

Use this function to attach IDMItem (or derived class) objects to the specified 
sourceOperation. This function is called when a direct manipulation begins over a 
control object. 

Returns true, if items are provided. 

virtual Boolean Supported On: 

provideSourceItems( PM 

const IDMSourceOperation::Handle& sourceOperation); 

provideTargetltemFor 

Use this function to replace generic IDMItem objects with a derived class during the 
processing of the initial target enter event. The event is processed in the target 
handler for a target window. 

The default implementation returns the item handle that was passed as the argument 
to the function. 


Supported On: 

PM 


424 Open Class Library Reference 



IDMItemProvider 


virtual IDMItem::Handle 

provideTarget!temFor( const IDMItem::Handle& dragltem); 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMItemProviderF or 



IDMItemProviderFor 


IBase 

IVBase 

IDMItemProvider 

IDMItemProviderFor 


_.None. 


_idmprov.hpp 


Member 

Page 

Member 

Page 

Constructor 

427 

provideT argetltemFor 

427 

provideSourceltems 

427 

'IDMItemProviderFor 

427 


IDMItemProviderFor is a template class that can be used to generate an 
IDMItemProvider derived class for your derived IDMItem classes. 

This class overrides the key functions of the class and dispatches static functions of 
your IDMItem derived class specified as the template argument. provideSourceltems 
will call the static generateSourceltems function of your IDMItem derived class. 

provideTargetltemFor creates a new object of your IDMItem derived class. This 
requires that your class provide a constructor that accepts as an argument a const 
IDMItem::Handle&. This argument is a handle to the generic IDMItem that the 
target handler creates. 

If you need to override additional IDMItemProvider functions (such as 
provideHelpFor and provideEnterSupport), you can derive your item provider class 
from this template class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 
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IDMItemProviderFor 

Use this constructor, the default constructor, to construct objects of this class. 

IDMItemProviderFor(); Supported On: 

PM 

"IDMItemProviderFor 


virtual 

"IDMItemProviderForO ; 


Supported On: 

PM 


Drag Item Support 

Use these members to provide event-specific support during a direct manipulation. These 
members are called when a direct manipulation begins over a control object, and during the 
processing of the initial target enter event. 

provideSou rceltems 

Use this function to delegate requests to the static function generateSourceltems of 
the template's argument class. <T>: :generateSourceItems should create appropriate 
source items and add them to this function's specified operation, where T represents 
the derived IDMItem class. 

This function is called when a direct manipulation begins over a control object. 
Returns true, if items are provided. 

virtual Boolean Supported On: 

provideSourceItems( PM 

const IDMSourceOperation::Handle& sourceOperation); 

provideTargetltemFor 

Use this function to create a new object of the template argument class, constructed 
from the generic target item passed to this function. The template argument class 
must provide a constructor that accepts as an argument a const IDMItem:-.Handle&. 

This function is called during the processing of the initial target enter event. 

virtual IDMItem: :Handle Supported On: 

provideTargetItemFor( const IDMItem::Handle& dragltem); PM 
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Inherited Public Functions 


IDMItemProvider 

pro videEnterS upport 

provideHelpFor 

provideLeaveSupport 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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I DM Menu Item 


IBase 

IVBase 

IRefCounted 

IDMItem 


IDMMenuItem 


_.None. 


_ idmmenit.hpp 


Member 

Page 

Member 

Page 

Constructor 
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430 
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Objects of the IDMMenuItem class are created by menu items when a direct 
manipulation commences over a menu item. 

Objects of this class possess the following attributes (in addition to those inherited 
from its base class): 

• Association with a source or target drag operation object. 

• Association with IDM::rmLibrary rendering mechanism and IDM::rfProcess 
rendering format. 

This class provides virtual functions that implement direct manipulation support for 
menu items. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 
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IDMMenultem 

[] IDMMenuItem( IDMSourceOperation* sourceOperation); Supported On: 

PM 

Use this constructor to construct items for the source of a direct manipulation. It 
accepts a pointer to the drag source operation. 

2 IDMMenuItem( const IDMItem: :Handle& dragltem); Supported On: 

PM 


Use this constructor to construct items for the target of a direct manipulation. It 
accepts a handle to a generic drag item. 

The generic drag item is passed to IDMItemProviderFor::provideTargetItemFor of the 
target menu item’s drag item provider. IDMItemProviderFor::provideTargetItemFor 
uses the generic drag item to construct a menu item drag item by calling this 
constructor. 


IDMMenultem 


virtual 

"TDMMenuItemO; 


Supported On: 

PM 


Menu Cleanup 

Use these members to handle cleanup of the menu after the direct manipulation has completed. 

_Use this function to process a source end event for a drag item that represents a 
menu item object. This function dismisses the menu that is the source of the direct 
manipulation. Derived classes should override this function when the default 
processing cannot be used. 

virtual Boolean Supported On: 

sourceEnd( IDMSourceEndEvent& sourceEndEvent); PM 


Menu Item Operations 

Use these members to set the supported direct manipulation operations for this class. 


supportedOperationsFor 

Returns IDMItem "linkable as the only operation this drag item supports. 


430 Open Class Library Reference 



IDMMenuItem 


virtual unsigned long 

supportedOperationsFor( const IString& str) const; 


Supported On: 

PM 


Source Items 

Use these members to access and manipulate source items involved in a direct manipulation. 


generateSou rceltems 

Use this function to generate a drag item that represents a menu item object selected 
in the source menu. 

static Boolean Supported On: 

generateSourceltems( IDMSourceOperation* sourceOperation); PM 


Inherited Public Functions 


IDMItem 

addRMF 

nativeRF 

setRequiresPreparation 

addType 

nativeRM 

setRMFs 

appendRMF 

nativeRMF 

setSelectedRMF 

attributes 

object 

setSourceName 

canBeCopied 

operator = 

setS ource Windo wHandle 

canBeLinked 

removeRMF 

setTargetName 

canBeMoved 

removeType 

setTrueType 

compressedRMF s 

Tenderer 

setTypes 

containerName 

requiresPreparation 

sourceDiscard 

contents 

rfF orThisProcess 

sourceEnd 

contentsSize 

rfFrom 

sourceltemFor 

deleteRMF 

rinf'From 

sourceName 

dropStatus 

rmFrom 

sourceOperation 

enableCopy 

rmfs 

sourcePrepare 

enableLink 

rmfsFrom 

sourcePrint 

enableMove 

selectedRMF 

sourceRender 

generateSourceltems 

setContainer 

source Window 

haslmage 

setContainerName 

source Windo wHandle 

hasType 

setContents 

supportedOperations 

image 

setDropStatus 

supportedOperationsFor 
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IDMItem 

imageOffset 

setGroup 

supportsRMF 

isContainer 

setlmage 

targetDrop 

isGroup 

setNativeRMF 

targetEnd 

isOnRemovableMedia 

setObject 

targetName 

isOpen 

setOnRemovableMedia 

targetOperation 

isReference 

setOpen 

tokenForWPSObject 

isTargetTheSource 

setReference 

trueType 

matchingRMFs 

setRenderer 

types 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDMItem 

generateSourceName 




Inherited Public Data 


IDMItem 

container 

linkable 

open 

copyable 

moveable 

prepare 

group 

none 

reference 
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IDMMLEItem 


IBase 

IVBase 

IRefCounted 

IDMItem 

IDMMLEItem 


_.None. 

—idmmleit.hpp 


Member 
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Multiple-line edit (MLE) controls create objects of the IDMMLEItem class when: 

• A direct manipulation operation begins in a source MLE. 

• A text object is dropped on a target MLE during a direct manipulation. 

Objects of this class have the following attributes in addition to those inherited from 
its base class: 

• An association with a source or target drag operation object 

• An association with the IDM::rmLibrary rendering mechanism and the 
IDM::rfProcess rendering format. If the text size is <= 255 bytes and the 
IDM::rmFile rendering mechanism is not being used, the IDM::rfText rendering 
format is used by this class's constructor. Otherwise, the IDM::rfSharedMem 
rendering format is used. 

This class provides virtual functions that implement direct manipulation support for 
the MLE. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMMLEItem 

Q IDMMLEItem( IDMSourceOperation* sourceOperation); Supported On: 

PM 

Use this constructor to construct items for the source of a direct manipulation. It 
accepts a pointer to the drag source operation. 

@ IDMMLEItem( const IDMItem: :Handle& dragltem); Supported On: 

PM 

Use this constructor to construct items for the target of a direct manipulation. It 
accepts a handle to a generic drag item. 

The generic drag item is passed to IDMItemProviderFor::provideTargetItemFor of the 
target multi-line edit’s drag item provider. 

IDMItemProviderFor::provideTargetItemFor uses the generic drag item to construct a 
multi-line edit drag item by calling this constructor. 

"IDMMLEItem 

virtual 

"IDMMLEItetn(); 

Drop Processing 

Use these members during the drop operation of a direct manipulation. 

_Use this function to process the drop of a drag item that represents a text object. 

This function sets the object into the target multi-line edit. Derived classes should 
override this function to insert the associated text object into the target multi-line edit 
when the default processing cannot be used. 

virtual Boolean Supported On: 

targetDrop( IDMTargetDropEvent& targetDropEvent); PM 


Supported On: 

PM 
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Source Items 

Use these members to access and manipulate source items involved in a direct manipulation. 


generateSourceltems 

Use this function to generate a drag item that represents a text object. The text object 
can be the entire contents of the source multi-line edit, or a selected portion. 

static Boolean Supported On: 

generateSourceltems( IDMSourceOperation* sourceOperation); PM 

Returns a pointer to the contents of the IString that contains the text being 
manipulated. The pointer can be cast to the type char * to directly access the text. 

virtual void* Supported On: 

object() const; PM 


Inherited Public Functions 


IDMItem 

addRMF 

nativeRF 

setRequiresPreparation 

addType 

nativeRM 

setRMFs 

appendRMF 

nativeRMF 

setSelectedRMF 

attributes 

object 

setSourceName 

canBeCopied 

operator = 

setSourceWindowHandle 

canBeLinked 

removeRMF 

setTargetName 

canBeMoved 

removeType 

setTrueType 

compressedRMF s 

Tenderer 

setTypes 

containerName 

requiresPreparation 

sourceDiscard 

contents 

rfF orThisProcess 

sourceEnd 

contentsSize 

rfFrom 

sourceltemFor 

deleteRMF 

rrnIFrom 

sourceName 

dropStatus 

rmFrom 

sourceOperation 

enableCopy 

rmfs 

sourcePrepare 

enableLink 

rmfsFrom 

sourcePrint 

enableMove 

selectedRMF 

sourceRender 

generateSourceltems 

setContainer 

source Window 

haslmage 

setContainerN ame 

source WindowHandle 
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IDMItem 

hasType 

setContents 

supportedOperations 

image 

setDropStatus 

supportedOperationsFor 

imageOffset 

setGroup 

supportsRMF 

isContainer 

setlmage 

targetDrop 

isGroup 

setNativeRMF 

targetEnd 

isOnRemovableMedia 

setObject 

targetName 

isOpen 

setOnRemovableMedia 

targetOperation 

isReference 

setOpen 

tokenForWPSObject 

isTargetTheSource 

setReference 

trueType 

matchingRMFs 

setRenderer 

types 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDMItem 

generate S ourceN ame 




Inherited Public Data 


IDMItem 

container 

linkable 

open 

copyable 

moveable 

prepare 

group 

none 

reference 
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IDMOperation 


IBase 

IVBase 

IRefCounted 

IDMOperation 


IDMSourceOperation 

IDMTargetOperation 
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444 
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IDMOperation is an abstract base class for the direct manipulation source and target 
drag operation classes. Objects of this class provide general-purpose information 
about direct manipulation operations. Access this information through its derived 
classes. 

Objects of this class have information about a direct manipulation as a whole: 

• An operation type (for example, copy, move, or link) 

• The position of the pointing device within the source or target window 

• The source of the operation (pointing device versus keyboard) 
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• The number of associated drag items, IDMItems 

• A pointer to the collection of IDMItems 

• A collection of IDMItem objects, one object for each item being dragged during 
this operation 

This class manages a drag item collection that associates drag items with this class. 

This class is an abstract base class. Your programs should only deal with objects of 
either of the derived classes IDMSourceOperation (p. 467) and IDMTargetOperation 
(p. 514). 


Public Functions 
Container Support 

Use these members to work with a container control in a direct manipulation. 

containerObject 

Returns a pointer to the container object over which the user has dragged or upon 
which the user has dropped. It returns 0 if one of the following conditions occur: 

• The target window is not a container, 

• The dragged items are positioned over container white space, or 

• The dragged items are dropped on container white space, 

IContainerObject* 
containerObject() const; 

setContainerObject 

Sets a pointer to the container object over which the user has dragged or upon which 
the user has dropped. 

IDMOperati on& 

setContainerObject( IContainerObject* object); 

setContainerRefreshOff 

Sets the refresh off for the given container. When drop processing returns or the drag 
is cancelled, refresh is turned on again. 

IDMOperation& Supported On: 

setContainerRefreshOff( IContainerControl* container); PM 


Supported On: 

PM 


Supported On: 

PM 
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setContainerRefreshOn 

Sets the refresh on for the container whose refresh was set off using 
IDMOperation: :setContainerRefreshOff (p. 440). The container is also refreshed. 

IDMOperati on& Supported On: 

setContai nerRefreshOn (); PM 


Drag Items 

Use these members to add, remove, and query the IDMItem objects involved in a direct 
manipulation. 

Associates another drag item with the operation. 

IDMOperation& Supported On: 

addltem( const IDMItem::Handle& newltem); PM 

Returns the drag item with a given position. If the position is not valid, 0 is 
returned. 

Note: Positions are 1-based. 

IDMItem::Handle 
item( unsigned position); 


Exceptions 

IlnvalidRequest The drag item handle was not returned. The specified index is not within 

the valid range. 


Supported On: 

PM 


numberOfltems 

Returns the number of items being dragged or dropped during a direct manipulation. 
This number is the same as the number of IDMItems added to the operation object. 

unsigned Supported On: 

numberOfltems(); PM 

...Removes a drag item from the operation. 

Q IDMOperati on& Supported On: 

removeltemj unsigned position); PM 

Use this version of the function to removes a drag item using a position. 

Note: Positions are 1-based. 
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0 IDMOperation& Supported On: 

removeItem( const IDMItem::Handle& itemToRemove); PM 

Use this version of the function to removes a drag item using a reference to the drag 
item handle. 


—Replaces a given drag item with another specified drag item. 
Note: Positions are 1-based. 


IDMOperation& 

replaceltem( unsigned position, 

const IDMItem::Handle& replacement); 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The drag item was not replaced. The specified index is not within the 

valid range. 


Drag Operations 

Use these members to set and query the default drag operation. 
-Returns the default direct manipulation operation. 


virtual unsigned long Supported On: 

operation() const; PM 

—Sets the default direct manipulation operation. 


virtual IDMOperation& 
setOperation( unsigned long op); 


Supported On: 

PM 


Drag Source Device 

Use these members to set and query the type of device that is used to initiate a direct 
manipulation. 

-Sets the type of the device that is the source of the direct manipulation operation. 

Note: Generally, you do not call this function. The operating system determines the 
source of a direct manipulation and the User Interface Class Library uses this 
function to save that information. 


virtual IDMOperation& 
setSource( Source source); 


Supported On: 

PM 
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IPM The source of a direct manipulation is always the pointing device, 

1DM: :pointingDevice. 

Returns the type of the device that was the source of the direct manipulation. 


IPM 


virtual Source Supported On: 

source() const; PM 

The source of a direct manipulation operation is always a pointing device, 

1DM: :pointingDevice. 


Pointing Device Position 

Use these members to set or query the pointing device’s position. 


Returns the pointing device position within the source or target window. 


virtual IPoint Supported On: 

position() const; PM 

_Sets the pointing device position for a direct manipulation. 


virtual IDMOperation& 

setPosition( IPoint position); 


Supported On: 

PM 


Source and Target Window Support 

Use these members to set and query the source and target windows. 


setSourceWindowHandle 

Sets the source window handle for a direct manipulation. 

Supported On: 

PM 

setTargetWindowHandle 

Sets the target window handle for a direct manipulation. 


virtual IDMOperation& 

setSourceWindowHandle( IWindowHandle window); 


virtual IDMOperation& 

setTargetWindowHandle( IWindowHandle window); 


Supported On: 

PM 


sourceWindow 

Returns a pointer to the source window for a direct manipulation. Returns 0 if the 
window is not valid. 
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virtual IWindow* Supported On: 

sourceWindow() const; PM 

sourceWindowHandle 

Returns the handle of the source window for a direct manipulation. Returns 0 if the 
window is not valid. 


virtual IWindowHandle 
sourceWindowHandle() const; 


Supported On: 

PM 


targetWindow 

Returns a pointer to the target window for a direct manipulation. Returns 0 if the 
window is not valid. For example, if the source window attempts to access the target 
window before the target window is known, the window is not valid. 

virtual IWindow* Supported On: 

targetWindow() const; PM 

targetWindowHandle 

Returns the handle of the target window for a direct manipulation. Returns 0 if the 
window is not valid. For example, if the source window attempts to access the target 
window before the target window is known, the window is not valid. 

virtual IWindowHandle Supported On: 

targetWindowHandle() const; PM 


Inherited Public Functions 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Constructors 

You can construct and destruct objects of this class. These members are used by derived classes 
of this class. 


IDMOperation 

Q IDMOperation( IDMTargetEnterEvent& event); Supported On: 

PM 

Use this function to construct an IDMOperation object by providing a reference to the 
target enter event. 

£ IDMOperation( IDMSourceBeginEvent& event); Supported On: 

PM 

Use this function to construct an IDMOperation object by providing a reference to the 
source begin event. 


IDMOperation 

This destructor deletes the drag item collection that manages associated drag items for 
this class. 


virtual Supported On: 

'IDMOperation(); PM 


Operation Services 

Use these members for various utility services. 

.Returns the pointer to the drag information structure. 


_DRAGINF0* Supported On: 

draglnfoO const; PM 

IPM Return value is a pointer to the Presentation Manager DRAGINFO structure. 

dragWasInterrupted 

Returns true if the direct manipulation is interrupted. Interrupts may occur when you 
do one of the following: 

• End the drag operation by pressing the <Esc> key 

• Request help while dragging over an object 
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• End the drag operation when the drop is rejected 


Boolean Supported On: 

dragWasInterrupted() const; PM 

— Sets the pointer to the drag information structure. 


IDMOperation& Supported On: 

setDraglnfoj _DRAGINF0* draglnfo); PM 

IPM The parameter, draglnfo, is a pointer to the Presentation Manager DRAGINFO 
structure. 

setDragResult 

Sets the overall result of a direct manipulation based upon the outcome of the 
operation. 


IDMOperation& 

setDragResult( Boolean result); 


Supported On: 

PM 


Public Data 
Drag Operations 

Use these members to set and query the default drag operation. 
Copy (the copy augmentation key is pressed). 


static const unsigned long Supported On: 

copy; PM 

Drag (no augmentation keys are pressed). This is the default operation. 


static const unsigned long Supported On: 

drag; PM 

..Link (the link augmentation keys are pressed). 


static const unsigned long Supported On: 

link; PM 

Move (the move augmentation key is pressed). 
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static const unsigned long Supported On: 

move; PM 

.Unknown (application-defined operation codes should be assigned values greater 

than this value). 


static const unsigned long 
unknown; 

Supported On: 

PM 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 
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IDMRenderer 


IBase 

IVBase 

IDMRenderer 


IDMSourceRenderer 
IDMT argetRenderer 


Mdmrendr.hpp 
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The IDMRenderer class is the base class for the direct manipulation source and target 
renderer classes. Objects of this class render drag items during a direct manipulation. 
Rendering is the transfer or re-creation of the dragged object from the source window 
to the target window. 

The IDMRenderer class defines the common protocol for both source and target 
Tenderers. The derived classes, IDMSourceRenderer (p. 479) and IDMTargetRenderer 
(p. 519), define the specific protocol for source Tenderers and target Tenderers, 
respectively. 

A generic renderer object has the following attributes: 

• A set of supported drag item types with which this renderer can work. An 
example of a drag item type is a string. 

• A set of supported rendering mechanisms and formats (RMFs). These RMFs 
describe the various means this renderer can use to transfer the dragged object. 

An example of a rendering mechanism is IDM::rmFile and an example of a 
rendering format is IDM::rfUnknown. 

You can perform two categories of operations on objects of this class: 
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• Queries to determine whether the Tenderer can render a given item. 

• Requests to perform one of the basic rendering processes. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IDMRenderer 

Q IDMRenderer( const char* rmfs. Supported On: 

const char* types); PM 

Use this constructor to create a special purpose Tenderer that renders items of a 
specific type using a specific RMF. You can construct a Tenderer by providing 
rendering mechanisms and formats (RMFs) and types that indicate which drag item 
can be rendered by this Tenderer. 

§ IDMRenderer (); Supported On: 

PM 

Use this constructor, the default constructor, to create a general purpose Tenderer that 
supports all item types using any library-supported RMF. 

"IDMRenderer 


virtual 

"IDMRendererO ; 


Supported On: 

PM 


Default Renderers 

Use these members to set and query the default source and target renderers. The default source 
and target renderers are added automatically to newly created source and target handlers. 


defaultSourceRenderer 

Returns the default source Tenderer, which is an IDMSourceRenderer object, unless 
the default has been set otherwise. 

static IDMSourceRenderer& Supported On: 

defaul tSourceRenderer(); PM 
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defauItTargetRenderer 

Returns the default target Tenderer, which is an IDMTargetRenderer object, unless the 
default has been set otherwise. 

static IDMTargetRenderer& Supported On: 

defaultTargetRenderer(); PM 

setDefaultSourceRenderer 

Sets the default source Tenderer. 


static void Supported On: 

setDefaul tSourceRenderer( PM 

IDMSourceRenderer& sourceRenderer); 

setDefauItTargetRenderer 

Sets the default target Tenderer. 


static void 

setDefaultTargetRenderer( 

IDMTargetRenderer& targetRenderer); 


Supported On: 

PM 


Supported Types and RMFs 

Use the following members to set and query the types and rendering mechanisms and formats 
(RMFs) supported by an object of this class. 


setSupportedRMFs 

Sets the RMFs supported by the Tenderer. 


virtual IDMRenderer& 
setSupportedRMFs( const char* rmfs); 


Supported On: 

PM 


setSupportedTypes 

Sets the drag item types supported by the Tenderer. 


virtual IDMRenderer& 
setSupportedTypes( const char* types); 


Supported On: 

PM 


supportedRMFs 

Returns the RMFs supported by the Tenderer. 
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virtual IString 

supportedRMFs() const; 


Supported On: 

PM 


supportedTypes 

Returns the drag item types supported by the Tenderer. 


virtual IString 

supportedTypes() const; 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

IEvent 

IDMEvent 

IDMSourceBeginEvent 


_.None. 
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Objects of the IDMSourceBeginEvent class represent the event that occurs upon the 
start of a direct manipulation at the source window. Objects are created by the source 
handler and passed as parameters to functions that participate in the handling of this 
event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMSourceBeginEvent 

Use this function to construct an IDMSourceBeginEvent from a generic IEvent (Vol. 
II) object. 


IDMSourceBeginEvent( const IEvent& event); 


Supported On: 

PM 
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IDMSourceBegin Event 


virtual 

"IDMSourceBeginEventO ; 


Supported On: 

PM 


Container Support 

Use these members to query information about a container control that is the source of a direct 
manipulation. 

_ Returns a pointer to the source container from which the source begin event 
occurred. 

virtual IContainerControl* Supported On: 

container() const; PM 

-..Returns the source container's identifier value. 


virtual unsigned long Supported On: 

containerId() const; PM 

Returns a pointer to the object over which the drag started. If the drag started over 
the container's white space or if the window is not a container, 0 is returned. 

Note: The white space of a container is an area that no container objects occupy. 


virtual IContainerObject* Supported On: 

object() const; PM 

Returns the position of the pointing device relative to the source container object's 
origin. 


virtual ISize 
offset() const; 


Supported On: 

PM 


Event Information 

Use these members to query event information for this class. 
-Returns the pointing device position. 


virtual IPoint Supported On: 

position() const; PM 

Returns the source of the drag operation. 
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virtual Source 
source() const; 


Supported On: 

PM 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMSourceDiscardEvent 


IBase 

IVBase 

IEvent 

IDMEvent 

IDMSourceDiscardEvent 


_.None. 


—idmevent.hpp 
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Objects of the IDMSourceDiscardEvent class are sent to the source window when the 
dragged objects are dropped on a shredder object. The event is used to return an 
indicator to the target, which identifies who has responsibility for deletion of the 
items or aborts the discard operation. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMSourceDiscardEvent 

Use this function to construct an IDMSourceDiscardEvent from a generic IEvent 
(Vol. II) object. 


IDMSourceDiscardEvent( const IEvent& event); 


Supported On: 

PM 
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IDMSourceDiscardEvent 


virtual 

"TDMSourceDiscardEvent (); 


Supported On: 

PM 


Event Information 

Use these members to set and query event information for this class. 


setSourceOperation 

Sets the handle of the drag source operation for this event. 


IDMSourceDiscardEvent& 
setSourceOperation ( 

const IDMSourceOperation::Handle& operation); 


Supported On: 

PM 


setWhoDiscards 

Sets the discard indicator, that identifies the following: 

• The source discards the item. This is the default. 

This is usually accomplished by calling the sourceDiscard function of the dragged 
item. 

• The target discards the item. 

The target is usually the desktop shredder. You should let it discard the object 
only if the object is a file; otherwise, it does not know how to discard your 
application objects. 

• The discard is aborted. 

IDMSourceDiscardEvent& 

setWhoDiscards( Discardlndicator indicator); 

sourceOperation 

Returns the handle of the drag source operation for this event. 

IDMSourceOperati on:: Handle Supported On: 

sourceOperation() const; PM 

...Returns the discard indicator identifying who should delete the items. 

virtual Discardlndicator Supported On: 

whoDiscards() const; PM 
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Supported On: 

PM 
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Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMSourceEndEvent 


IBase 

IVBase 

IEvent 

IDMEvent 

IDMSourceEndEvent 


_.None. 

Mdmevent.hpp 

Member Page Member Page 
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dragltem 459 'IDMSourceEndEvent 458 

Objects of the IDMSourceEndEvent class are sent to the direct manipulation source 
window when a target Tenderer has completed the rendering of a drag item. One of 
these events is expected for each of the drag items involved in a direct manipulation. 


Public Functions 


Constructors 

You can construct and destruct objects of this class. 


IDMSourceEndEvent 


Use this function to construct an IDMSourceEndEvent from a generic IEvent (Vol. II) 
object. 


IDMSourceEndEvent( const IEvent& event); 


Supported On: 

PM 


"IDMSourceEndEvent 


virtual 

'IDMSourceEndEvent (); 


Supported On: 

PM 
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Rendering 

Use these members to query information about the rendering process. 

_Returns the handle of drag item for which the target has completed rendering. 


virtual IDMItem::Handle 
dragltem() const; 


Supported On: 

PM 


wasTargetSuccessful 

Returns true if the target successfully completed rendering. 


virtual Boolean 
wasTargetSuccessful() const; 


Supported On: 

PM 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMSourceHandler 


IBase 

IVBase 

IHandler 

IDMHandler 

IDMSourceHandler 


_.None. 
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Objects of the IDMSourceHandler class process events occurring on the source of a 
direct manipulation. You must add an object of this class to a window so it can 
support direct manipulation. This handler does not allow objects to be dropped on a 
window. See IDMTargetHandler (p. 504) for information about dropping objects on 
a window. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMSourceHandler 

[J IDMSourceHandler( IContai nerControl * contai nerControl); Supported On: 

PM 
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§ IDMSourceHandler( IWindow* window); Supported On: 

PM 

Use this function to create an object of this class by providing a pointer to an 
IWindow object. The constructed handler is automatically attached to the specified 
window. 

g IDMSourceHandler( IEntryField* entryField); Supported On: 

PM 

Use this function to create an object of this class by providing a pointer to an entry 
field object. The constructed handler is automatically attached to the specified entry 
field. 

0 IDMSourceHandl er ( IMul ti Li neEdi t* mul ti LineEdi t); Supported On: 

PM 

Use this function to create an object of this class by providing a pointer to a 
multi-line edit (MLE) object. The constructed handler is automatically attached to the 
specified MLE. 

g IDMSourceHandl er (); Supported On: 

PM 

This is the default constructor. 

"IDMSourceHandler 

virtual Supported On: 

'IDMSourceHandler(); PM 


Renderer Processing 

These members override the rendering functions defined in the base IDMHandler class. Use 
them to access the IDMSourceRenderer objects involved in a direct manipulation. Objects of this 
class render the dragged objects that are compatible with the rendering mechanisms and formats 
that the User Interface Class Library supports. 

_.Adds the specified renderer to the set of candidates maintained by this handler and 
used to render objects dragged from a source window where this handler is attached. 

The renderer is added to the end of the renderer collection. 

Note: Renderers are maintained by positions, which are 1-based. 
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virtual IDMSourceHandler& Supported On: 

addRenderer ( const IDMSourceRenderer& newRenderer); PM 

numberOfRenderers 

Returns the number of Tenderers associated with the source handler. 


virtual unsigned 
numberOfRenderers(); 


Supported On: 

PM 


removeRenderer 

Removes a specified Tenderer from this handler. 

Note: Renderers are maintained by positions, which are 1-based. 

virtual IDMSourceHandl er& Supported On: 

removeRenderer( const IDMSourceRenderer& rendererToRemove); PM 

Returns the Tenderer with the specified position. 

Note: Renderers are maintained by positions, which are 1-based. 

virtual IDMSourceRenderer* Supported On: 

renderer( unsigned position); PM 


replaceRenderer 

Replaces the given tenderer with another specified tenderer. 

Note: Renderers are maintained by positions, which are 1-based. 


virtual IDMSourceHandler& 
replaceRenderer( unsigned position, 

const IDMSourceRenderer& replacement); 


Supported On: 

PM 


_Sets the Tenderer for this handler. Removes any pre-existing renderers. 


virtual IDMSourceHandler& 

setRenderer( const IDMSourceRenderer& newRenderer); 


Supported On: 

PM 


Inherited Public Functions 


IDMHandler 

defauItSourceHandler 

enableDragDropFor 

enableDropOn 
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IDMHandler 

defaultTargetHandler 

enableDragF rom 

setDefaultSoureeHandler 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

These members dispatch the various events for a direct manipulation source. 

dispatchHandlerEvent 

This function overrides of the default handler's dispatcher. It processes the direct 
manipulation events for the source. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM 


Event Processing 

These members are dispatched in response to specific direct manipulation events for the source. 

- Called to process the start of a direct manipulation in response to a system begin 
drag event. Initial processing invokes IDMSourceOperation::allocateOperation. Next, 
a pointer to the drag item provider is obtained by calling IWindow::itemProvider. 
Afterwards, IDMItemProvider::provideSourceItems is invoked to retrieve the items to 
be dragged. IDMSourceOperation::fmdRenderersFor is called to find appropriate 
source Tenderers for the items that were provided. If there are items to be dragged, 
IDMSourceOperation::begin is called to begin the direct manipulation. 
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virtual Boolean 

sourceBegin( IDMSourceBeginEvent& event. 
Boolean container = true); 


Supported On: 

PM 


sourceDiscard 

Called to indicate that an item or items have been dropped on a shredder object. The 
source response determines who deletes the items or if the operation is cancelled. 

The default implementation dispatches IDMSourceRenderer::sourceDiscard. 

virtual Boolean Supported On: 

sourceDiscard( IDMSourceDiscardEvent& event); PM 

_Called to indicate that a given item has been processed by the target. The default 
implementation for this class dispatches IDMSourceRenderer::sourceEnd on the 
corresponding drag item object. After all end conversations are received, the 
IDMSourceOperation object is deleted. 


virtual Boolean 

sourceEnd( IDMSourceEndEvent& event); 


Supported On: 

PM 


sourcePrepare 

Called to indicate to the source that rendering is ready to start. Requests for 
rendering preparation are made within the source item constructors. The default 
implementation in this class dispatches IDMSourceRenderer::sourcePrepare on the 
corresponding drag item object. 

virtual Boolean Supported On: 

sourcePrepare( IDMSourcePrepareEvent& event); PM 

—Called to indicate that a drag item or items have been dropped on a printer object. 
The source response determines who prints the items or if the operation is cancelled. 
The default implementation dispatches IDMSourceRenderer::sourcePrint. 

virtual Boolean Supported On: 

sourcePrint( IDMSourcePrintEvent& event); PM 


sourceRender 

Called to start the rendering of a drag item by the source Tenderer. The default 
implementation for this class dispatches IDMSourceRenderer::sourceRenderer on the 
drag item object. 

virtual Boolean Supported On: 

sourceRender( IDMSourceRenderEvent& event); PM 
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Implementation 

These members provide utilities used to implement this class. They are used by the User 
Interface Class Library. 


allocateOperation 

Use this function to create a new IDMSourceOperation object. 

This function is called when the source handler is handling the processing of a new 
direct manipulation. Derived classes should override this function and return a class 
derived from IDMSourceOperation. 

Returns a handle to the source operation object. 

virtual IDMSourceOperation::Handle Supported On: 

al1ocateOperation( IDMSourceBeginEvent& event, PM 

DraglmageStyle dragltemStyle) const; 


findRendererFor 

Use this function to find the appropriate source Tenderer for the drag item. Returns 
the position of the Tenderer, or 0 if a Tenderer cannot be found. 

virtual unsigned Supported On: 

findRendererFor( const IDMItem: :Handle& item); PM 

findRenderersFor 

Use this function to find the appropriate source Tenderers for the specified source 
operation. 


virtual Boolean 
findRenderersFor( 

const IDMSourceOperation::Handle& sourceOperation); 


Supported On: 

PM 


Inherited Protected Functions 


IDMHandler 

addRenderer 

numberOfRenderers 

Tenderer 

isContainerControl 

removeRenderer 

replaceRenderer 
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IDMSourceHandler 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMSourceOperation 


IBase 

IVBase 

IRefCounted 

IDMOperation 

IDMSourceOperation 


_.None. 

—idmsrccp.hpp 
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Objects of the IDMSourceOperation class provide information about direct 
manipulation source operations. You can access to this information using 
IDMItem::sourceOperation (p. 404). 

Objects of this class are not intended to be created by application programmers. The 
source event handler class, IDMSourceHandler, creates them. 

You can access an object of this class using IDMSourceOperation: :Handle which 
reference counts the object. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMSourceOperation 

Use this function to create objects of this class by providing a reference to the source 
begin event and a drag image style. 
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IDMSourceOperation 


IDMSourceOperation( Supported On: 

IDMSourceBeginEvent& event, PM 

DraglmageStyle dragStyle = IDM::systemlmages); 

IDMSourceOperation 

This destructor will enable the container refresh and refresh the container if a 
container is the source of the direct manipulation. 


virtual 

'IDMSourceOperation(); 


Supported On: 

PM 


Drag Image Support 

Use these functions to set and query the drag image style and the stacking percentage that 
determines the placement of stacked drag images. 

_ Returns the drag image style for the source operation. 


virtual DraglmageStyle 
imageStyle() const; 


Supported On: 

PM 


setlmageStyle 

Sets the drag image style for the source operation. 


virtual IDMSourceOperation& 
setImageStyle( 

DraglmageStyle draglmageStyle = IDM::systemlmages); 


Supported On: 

PM 


setStackingPercentage 

Sets the stacking percentage that is used to calculate the placement of the next 
"stacked" image, when the drag image style, IDM::stack3AndFade or 
IDM::allStacked, is specified. 


virtual IDMSourceOperation& Supported On: 

setStackingPercentage( const IPai r& stackingPercentage); PM 

stackingPercentage 

Returns the stacking percentage that is used to calculate the placement of the next 
"stacked" image, when the drag image style, IDM::stack3AndFade or 
IDM::allStacked, is specified. 
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I Pai r Supported On: 

stackingPercentage() const; PM 


Implementation 

These members provide utilities used to implement this class. They are used by the User 
Interface Class Library. 

Initiates the dragging of the objects. 

Note: Generally, you do not call this function. This function is called by an 

IDMSourceHandler object during the processing of a source begin event. 


IDMSourceOperation& 
begin(); 

Supported On: 

PM 

Exceptions 

IAccessError 

The drag operation was not started. The drag information could not be 


allocated. The system resources may be exhausted. 

IAccessError 

The drag operation was not started. Allocation of a drag item failed. 

IAccessError 

The drag operation was not started. A drag item may be invalid. 


Operation Services 

Use these members for various operational services. 

-Returns the default direct manipulation operation. Use this function to determine the 
actual operation that occurred at the target, after the drop has occurred. 

virtual unsigned long Supported On: 

operation() const; PM 


operationFrom 

Retrieves a handle to the drag source operation from the drag information structure. 


(PM 


static Handle Supported On: 

operationFrom( _DRAGINF0* draglnformation); PM 

The parameter, draglnformation, is a pointer to the Presentation Manager 
DRAGINFO structure. 


Exceptions 

IAccessError The source operation handle was not retrieved. The drag information is not 

accessible. 
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IDMSourceOperation 


Pointing Device Position 

Use these members to set or query the pointing device’s position. 

_Returns the position of the pointing device relative to the source container object's 
origin. 


virtual ISize 
pointerOffset() const; 


Supported On: 

PM 


setPointerOffset 

Sets the position of the pointing device relative to the source container object's origin. 


virtual IDMSourceOperation& 
setPointerOffset( const ISize& offset); 


Supported On: 

PM 


Inherited Public Functions 


IDMOperation 

addltem 

replaceltem 

setSourceWindowHandle 

containerObject 

setContainerObj ect 

setTargetWindowHandle 

item 

setContainerRefreshOff 

source 

numberOfltems 

setContainerRefreshOn 

source Window 

operation 

setOperation 

source WindowHandle 

position 

setPosition 

targetWindow 

removeltem 

setSource 

targetWindo wHandle 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Functions 


IDMOperation 

draglnfo 

dragW aslnterrupted 

setDraglnfo 


Inherited Public Data 


IDMOperation 

copy 

drag 

link 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Type Definitions 

typedef Reference < IDMSourceOperation > Handle; 

IDMSourceOperation::Handle provides access to the IDMSourceOperation objects 
associated with a direct manipulation operation. Handle manages the references to 
the IDMSourceOperation object and ensures that this object is not deleted until the 
direct manipulation operation is completed. 

Use Handle to reference a source operation handle within this class and 
IDMSourceOperation::Handle externally. 

Handle provides a operator that enables instances to be treated just like a pointer 
to an IDMSourceOperation object. 
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IDMSourcePrepareEvent 


IBase 

IVBase 

IEvent 

IDMEvent 

IDMSourceRenderEvent 

IDMSourcePrepareEvent 


_.None. 

__idmevent.hpp 


Member Page 
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altemateWindow 473 

altemateWindowHandle 473 

noSourceRendering 474 

setAltemateWindowHandle 473 


Member 

Page 

setNoSourceRendering 
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setT argetCanRetry 

474 

targetCanRetry 

474 

'IDMSourcePrepareEvent 

473 


Objects of the IDMSourcePrepareEvent class are sent to the source window when the 
source Tenderer for a given object has indicated notification is necessary before 
starting the source rendering of a drag item. 

Objects of this class provide all the query functions inherited from 
IDMSourceRenderEvent (p. 484). In addition, functions are provided to return the 
following information to the target: 

• An alternate source window with which the target can communicate during 
rendering 

• Two result flags indicating whether the target: 

Performs the rendering 

Retries the rendering with a different rendering mechanism and format 


Public Functions 
Alternate Window 

Use these members to set and query the alternate source window. The alternate source window 
can be used to implement source rendering on a secondary thread. 
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alternateWindow 

Returns a pointer to the alternate source window. 

Supported On: 

PM 

alternateWindowHandle 

Returns the handle of the alternate source window. 


virtual IWindow* 
alternateWindow() const; 


virtual IWindowHandle Supported On: 

alternateWindowHandle() const; PM 

setAlternateWindowHandle 

Sets the handle of the alternate source window. 


IDMSourcePrepareEvent& 

setAlternateWindowHandle( const IWindowHandle& window); 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. 

IDMSourcePrepareEvent 

Use this function to consUuct an IDMSourcePrepareEvent from a generic IEvent (Vol. 
II) object. 

IDMSourcePrepareEvent( const IEventS event); Supported On: 

PM 

"IDMSourcePrepareEvent 

virtual Supported On: 

'IDMSourcePrepareEvent (); PM 


Rendering 

Use these members to provide the render preparation support. The results of the preparation are 
returned to the target. 
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noSourceRendering 

Returns true if only the target can perform the rendering. 

The default is false. 

Bool ean Supported On: 

noSourceRendering() const; PM 

setNoSourceRendering 

Sets the no source rendering flag that indicates that only the target can perform the 
rendering. 

IDMSourcePrepareEvent& 
setNoSourceRendering( Boolean flag); 

setTargetCan Retry 

Sets the retry flag that indicates if the target can retry a failed rendering with a 
different rendering mechanism and format. 

IDMSourcePrepareEvent& Supported On: 

setTargetCanRetry( Boolean flag); PM 


Supported On: 

PM 


targetCanRetry 

Returns true if the target can retry a failed rendering with a different rendering 
mechanism and format. 

The default is false. 

Bool ean Supported On: 

targetCanRetry() const; PM 


Inherited Public Functions 


IDMSourceRenderEvent 

alternate Window 

dragltem 

setRetry 

alternate WindowHandle 

selectedFormat 

setTargetlnfo 

canRetry 

selectedMechanism 

targetlnfo 

completion 

setCompletion 

targetName 
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IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMSourcePrintEvent 


IBase 

IVBase 

IEvent 

IDMEvent 

IDMSourcePrintEvent 


_.None. 

Mdmevent.hpp 
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477 
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477 
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Objects of the IDMSourcePrintEvent class are sent to the source window when the 
user drops the dragged objects on a printer object. The event returns an indicator to 
the target window, which identifies who prints the items or aborts the print operation. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMSourcePrintEvent 

Use this function to construct an IDMSourcePrintEvent from a generic IEvent (Vol. 

II) object. 

IDMSourcePrintEvent( const IEvent& event); Supported On: 

PM 


Exceptions 

IlnvalidRequest The object for the source print event was not created. The drag item may 

be invalid. 
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IDMSourcePrintEvent 

virtual 

~IDMSourcePrintEvent(); 


Supported On: 

PM 


Print Support 

Use these members to set and query printing attributes. 


printDestination 

Returns the pointer to the print destination structure. 


_PRINTDEST* Supported On: 

printDestination() const; PM 

IPM Return value is a pointer to the Presentation Manager PRINTDEST structure. 

setSourceOperation 

Sets the handle to the drag source operation for this event. 


IDMSourcePrintEvent& Supported On: 

setSourceOperation( const IDMSourceOperation::Handle& operation); PM 


setWhoPrints 

Sets the print indicator, which identifies the following: 

• The source prints the item. This is the default. 

• The target prints the item. 

• The print operation is aborted. 

Supported On: 

PM 


IDMSourcePrintEvent& 

setWhoPrints( Printlndicator indicator); 


sourceOperation 

Returns the handle to the drag source operation for this event. 

IDMSourceOperation::Handle Supported On: 

sourceOperation() const; PM 

- Returns the print indicator identifying who should print the items. 
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virtual Printlndicator 
whoPrints() const; 


Supported On: 

PM 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 
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messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMSourceRenderer 


IBase 

IVBase 

IDMRenderer 

IDMSourceRenderer 


_.None. 
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Objects of the IDMSourceRenderer class provide source rendering support for a direct 
manipulation. Objects of this class are registered with the source handler. The 
handler selects a best match Tenderer by calling !DMSourceHandler::findRendererFor 
(p. 465) for a given drag item and invokes the rendering functions of this Tenderer 
when source rendering events occur. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMSourceRenderer 

Q IDMSourceRenderer) const char* rmfs. Supported On: 

const char* type = IDM::any); PM 

Use this function to create objects of this class by providing rendering mechanisms 
and formats (RMFs) and types that indicate which drag item can be rendered by this 
source Tenderer. 
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IDMSourceRenderer 


2 IDMSourceRenderer(); 


Supported On: 

PM 


This is the default constructor. 

When this constructor is used, the Tenderer supports any type and all of the default 
source RMFs supported by the User Interface Class Library: 

(IDM::rmLibrary)x(IDM::rfProcess,IDM::rfText,IDM::rfSharedMem), 

(IDM: :rmDiscard,IDM: :rmPrint)x( IDM: :unKnown), <1DM: :rmFile,IDM: :rfText> 

IDMSourceRenderer 


virtual 

"IDMSourceRendererO; 


Supported On: 

PM 


Source and Target Rendering 

Use these members to support the implementation of source rendering. Members that you can 
use to support target rendering are identified on an individual basis. 

-Returns true if the Tenderer can render items with the specified attributes. This 
function is used when the drag begins. 

Note: This function can be used for either source or target rendering, 
virtual Boolean 

canRender( const IString& types); 

informTargetOfCompletion 

Informs the target when source rendering has completed on the drag item. It is not 
used by any of the default tenderers supported by the User Interface Class Library. 

Note: This function can be used for source rendering only. 


virtual IDMSourceRenderer& Supported On: 

informTargetOfCompletion( IDMSourceRenderEvent& event); PM 


Exceptions 

IlnvalidRequest 

The target could not be informed that source rendering completed. The 
drag transfer information is invalid. 

IAccessError 

The target could not be informed that source rendering completed. Posting 
the target end event to the target failed. 


Supported On: 

PM 
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sourceDiscard 

Called by lDMSourceHandler::sourceDiscard (p. 464) when the source has 
responsibility for discarding the item. 

virtual IDMSourceRenderer& Supported On: 

sourceDiscard( IDMSourceDiscardEvent& event); PM 

- Called when the target informs the source that it has finished processing the data 
associated with the dropped item. 

Note: This function can be used for either source or target rendering. 

virtual IDMSourceRenderer& Supported On: 

sourceEnd( IDMSourceEndEvent& event); PM 


sourcePrepare 

Called when an item indicates it requires preparation, which can be any activity the 
source needs to perform before rendering the data. 

For example, the drag item may require the source to create a secondary thread when 
source rendering occurs. This allows the system to remain responsive to the users. 

Note: This function can be used for source rendering only. 

virtual IDMSourceRenderer& Supported On: 

sourcePrepare( IDMSourcePrepareEvent& event); PM 

- Called by lDMSourceHandler::sourcePrint (p. 464) when the source has 
responsibility for printing the item. 

virtual IDMSourceRenderer& Supported On: 

sourcePrint( IDMSourcePrintEvent& event); PM 


sourceRender 

Called when the target Tenderer requests that a source Tenderer render an item. 
Note: This function can be used for source rendering only. 


virtual IDMSourceRenderer& 

sourceRender( IDMSourceRenderEvent& event); 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The source Tenderer could not render the item. The rendering format is 

invalid. 


© IBM Corp. 1992, 1995 


IDMSourceRenderer 481 




IDMSourceRenderer 


Exceptions 

IlnvalidRequest The source Tenderer could not render the item. The rendering mechanism 

is invalid. 


Inherited Public Functions 


IDMRenderer 

defaultSoureeRenderer 

setDefaultSourceRenderer 

setSupportedRMFs 

defaultTargetRenderer 

setDefaultT argetRenderer 

setSupportedTypes 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Renderer Specifics 

Use these members to process the different rendering operations that are specific to the supported 
rendering mechanisms and formats. 

-Called when a discard event occurs and this renderer must discard a drag item. The 
User Interface Class Library performs no default processing in this function. 

virtual Boolean Supported On: 

doDiscard( IDMSourceDiscardEvent& event); PM 

Called when a print event occurs and this renderer must print a drag item. The User 
Interface Class Library performs no default processing in this function. 

virtual Boolean Supported On: 

doPrint( IDMSourcePrintEvent& event); PM 

-Called when a render event occurs and this renderer must use source rendering to 
render a drag item. The User Interface Class Library uses this function to implement 
the support for the <IDM::rmLibrary,IDM::rfSharedMem> rendering mechanism and 
format. 
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virtual Boolean Supported On: 

doRender( IDMSourceRenderEvent& event); PM 

doRenderEnd 

Called when an end event occurs and this Tenderer must end the render operation. 

The User Interface Class Library performs no default processing in this function. 

virtual Boolean Supported On: 

doRenderEnd( IDMSourceEndEvent& event); PM 

doRenderPrepare 

Called when a render prepare event occurs and this Tenderer must use source 
rendering to render a drag item. The User Interface Class Library uses this function 
to implement the support for the <IDM::rmLibrary,IDM::rfSharedMem> rendering 
mechanism and format. 


virtual Boolean 

doRenderPrepare( IDMSourcePrepareEvent& event); 


Supported On: 

PM 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IEvent 

IDMEvent 

IDMSourceRenderEvent 


IDMSourcePrepareEvent 
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Objects of the IDMSourceRenderEvent class represent direct manipulation rendering 
events. Such events are created and dispatched to source handlers when a direct 
manipulation target Tenderer requests source rendering. 

In addition to the standard IEvent attributes of event and window identifiers, such 
objects also have: 

• An associated drag item object 

• An alternate window handle 

• A target window handle 

• A rendering mechanism and format (RMF) selected by the target 

• A target name 

• Target-defined information 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IDMSourceRenderEvent 

Use this function to construct an IDMSourceRenderEvent from a generic IEvent (Vol. 
II) object. 

IDMSourceRenderEvent( const IEvent& event); Supported On: 

PM 


Exceptions 

IlnvalidRequest The object for the source render event was not created. The drag transfer 

information may be invalid. 


IDMSourceRenderEvent 


virtual 

"IDMSourceRenderEventO ; 


Supported On: 

PM 


Rendering 

Use these members set and query attributes related to rendering. 


alternateWindow 

Returns a pointer to the alternate source window. The alternate window can be used 
to implement source rendering on a secondary thread. 

virtual IWindow* 
alternateWindow() const; 

alternateWindowHandle 

Returns the handle of the alternate source window. The alternate window can be 
used to implement source rendering on a secondary thread. 

virtual IWindowHandl e Supported On: 

alternateWindowHandle() const; PM 


Supported On: 

PM 
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IDMSourceRenderEvent 


.Returns true if the Tenderer processing the event can reUy processing the event if a 

failure occurs. This flag is passed to the target Tenderer by 
IDMSourceRenderer::informTargetOfCompletion (p. 480). 

The default is false. 


virtual Boolean Supported On: 

canRetry() const; PM 

_ Returns the flag that indicates if the rendering completed. This flag is passed to the 
target Tenderer by lDMSourceRenderer::informTargetOfCompletion (p. 480). 

The default is IDM::renderOk. 


virtual IDM: :RenderCompletion Supported On: 

completion() const; PM 

..Returns the IDMItem handle corresponding to the drag item being rendered. 


virtual IDMItem::Handle 
dragltem() const; 


Supported On: 

PM 


selectedFormat 

Returns the selected rendering format. 


virtual IString Supported On: 

selectedFormat() const; PM 

selectedMechanism 

Returns the selected rendering mechanism. 


virtual IString 
selectedMechanism() const; 


Supported On: 

PM 


setCompletion 

Sets the completion flag that indicates that the rendering completed successfully. 

virtual IDMSourceRenderEvent& Supported On: 

setCompletion( IDM:: RenderCompl eti on code); PM 

_Sets the reUy flag that indicates the Tenderer processing the event can reUy a failed 
rendering. 
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virtual IDMSourceRenderEvent& Supported On: 

setRetry( Boolean allowRetry = true); PM 

__Sets information that is passed to the target tenderer. 

virtual IDMSourceRenderEvent& 

setTargetInfo( unsigned long info); 

.. Returns the target defined information. 

Note: This is an extra field the target can use to pass additional information to the 
source. You can use it to implement the specialized behavior for your rendering 
mechanisms and formats. 


Supported On: 

PM 


virtual unsigned long Supported On: 

targetInfo() const; PM 

__Returns the target render-to name. The source can use this field to indicate to the 
target where it has placed the data it has rendered (that is, the name of a shared 
memory segment or file). 


virtual IString 
targetName() const; 


Supported On: 

PM 


targetWindow 

Returns a pointer to the target window. 


virtual IWindow* Supported On: 

targetWindow() const; PM 

targetWindowHandle 

Returns the handle of the target window. 


virtual IWindowHandle 
targetWindowHandle() const; 


Supported On: 

PM 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 
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IE vent 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMTargetDropEvent 


IBase 
IVBase 
IEvent 
IDMEvent 
IDMT argetE vent 
IDMT argetDropEvent 


_.None. 
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Objects of the IDMTargetDropEvent class encapsulate direct manipulation events 
occurring at the target handler when a user drops a drag item onto a target window. 
Target handlers access information about the dropped items from the stored 
IDMTargetOperation object created as part of the IDMTargetEnterEvent processing. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMTargetDropEvent 

Use this function to construct an IDMTargetDropEvent from a generic IEvent (Vol. 
II) object. 


IDMTargetDropEvent( const IEvent& event); 


Supported On: 

PM 
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IDMTargetDropEvent 


Exceptions 

IAccessError The object for the target drop event was not created. The drag information 

is not accessible. 


"IDMTargetDropEvent 


virtual 

"IDMTargetDropEvent (); 


Supported On: 

PM 


Container Support 

Use these members to provide drop support for the container drop event. 

-Returns a pointer to the container where the target drop event occurred. 

virtual IContainerControl* Supported On: 

container() const; PM 

-Returns the target container's identifier value. 

virtual unsigned long Supported On: 

containerld() const; PM 

Returns a pointer to the object over which the target drop event occurred. If this 
event occurred over the container's white space or the window is not a container, 0 is 
returned. 

Note: The white space of a container is an area that no container objects occupy. 


virtual IContainerObject* 
object() const; 


Supported On: 

PM 


Target Drop Information 

Use these members to set and query drop and target information. 

— Returns the position where the drop occurred. This position is given in desktop 
coordinates. 

virtual IPoint Supported On: 

dropPosition() const; PM 
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setDropPosition 

Sets the position where the drop occurred. This position is given in desktop 
coordinates. 

virtual IDMTargetDropEvent& 

setDropPosition( const IPoint& position); 

_. Passes information to the target. 

virtual IDMTargetDropEvent& 

setTargetInfo( unsigned long info); 

_ Returns the target defined information. 

Note: This is an extra field the source can use to pass additional information to the 
target. You can use it to implement the specialized behavior for your rendering 
mechanisms and formats. 


Supported On: 

PM 


Supported On: 

PM 


virtual unsigned long 
targetInfo() const; 


Supported On: 

PM 


Inherited Public Functions 


IDMTargetEvent 

presSpace 

releasePresSpace 



IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 
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parameter2 

setHandle 
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result 

setResult 
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IVBase 

asDebuglnfo 

asString 
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IDMTargetDropEvent 


IBase 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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_.None. 
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Objects of the IDMTargetEndEvent class are sent to the target window when the 
source window completes the rendering of a drag item. The event provides source 
window information about the item rendering results. 

Note: The User Interface Class Library does not process this event in any of its 
default rendering mechanisms and formats. 


Public Functions 
Alternate Window 

Use these members to query the alternate source window. The alternate source window can be 
used to implement source rendering on a secondary thread. 


alternateWindow 

Returns a pointer to the alternate source window. 


virtual IWindow* 
alternateWindow() const; 


Supported On: 

PM 
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alternateWindowHandle 

Returns the handle of the alternate source window. 


virtual IWindowHandle 
alternateWindowHandle() const; 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. 


IDMTargetEndEvent 

Use this function to construct an IDMTargetEndEvent from a generic IEvent (Vol. II) 
object. 


IDMTargetEndEvent( const IEvent& event); Supported On: 

PM 


Exceptions 

IlnvalidRequest 

The object for the target end event was not created, 
information may be invalid. 

The drag transfer 

IlnvalidRequest 

The object for the target end event was not created, 
invalid. 

The drag item may be 


"IDMTargetEndEvent 


virtual 

"TDMTargetEndEvent (); 


Supported On: 

PM 


Rendering 

Use these members to provide the rendering results returned by the source. 

_Returns the handle of the drag item that the source has completed rendering. 


virtual IDMItem::Handle 
dragltem() const; 


Supported On: 

PM 


renderingFailed 

Returns true if the source cannot perform the rendering operation. The target can 
accept a retry, but if the target is not prepared to retry, it must call 
IDMTargetRenderer::informSourceOfCompletion to end the operation. 
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Boolean 

renderingFailed() const; 


Supported On: 

PM 


targetCanRetry 

Returns true if the target can retry its part of a failed rendering. The source has 
successfully completed its part of the rendering. 

Boolean 

targetCanRetry() const; 

_ Returns the target defined information. 

Note: This is an extra field the source can use to pass additional information to the 
target. You can use it to implement the specialized behavior for your rendering 
mechanisms and formats. 


Supported On: 

PM 


virtual unsigned long 
targetInfo() const; 


Supported On: 

PM 


Inherited Public Functions 


IEvent 
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setDispatchingHandle 
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Inherited Protected Data 
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Objects of the IDMTargetEnterEvent class encapsulate direct manipulation events 
occurring at the target handler when a drag operation enters a potential target 
window. Target handlers access information about the dragged items from the 
associated IDMTargetOperation object. 

The event result field is of particular importance for these event objects. The result 
indicates whether the dragged objects can be dropped on this target, and if so, what 
the default operation is. This class provides specialized functions to set the 
components of the event result. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMTargetEnterEvent 

Use this function to construct an IDMTargetEnterEvent from a generic IEvent (Vol. 
II) object. 
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IDMTargetEnterEvent( const IEvent& event); 


Supported On: 

PM 


"IDMTargetEnterEvent 


virtual 

"TDMTargetEnterEventO; 


Supported On: 

PM 


Container Support 

Use these members to query information about the container control that was just entered. 

Returns a pointer to the container within which the target enter event occurred. 

virtual IContainerControl* Supported On: 

container() const; PM 

-Returns the target container's identifier value. 


virtual unsigned long Supported On: 

containerId() const; PM 

—Returns true if the target enter event was generated above the first list item in one 
of the list views of a container. An example of a container list view is details view. 

virtual Boolean Supported On: 

i sAboveFi rst() const; PM 

-Returns true if the target enter event was generated above the first list item, between 
list items, or after the last list item in one of the list views of a container. An 
example of a container list view is details view. 

Returns false if the event was generated over a list item. 


virtual Boolean Supported On: 

i sDragAfter() const; PM 

Returns a pointer to the object over which the target enter event occurred. If the 
event occurred over the container's white space or the window is not a container, 0 is 
returned. 

Note: The white space of a container is an area that no container objects occupy. 
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virtual IContainerObject* 
object() const; 


Supported On: 

PM 


Event Information 

Use these members to set and query event information for this class. 


defaultOperation 

Returns the default operation for the target. 


virtual unsigned long 
defaultOperation() const; 


Supported On: 

PM 


droplndicator 

Returns the drop indicator that is one of the following: 

• IDMunotOk 

• IDM::ok 

• IDM::operationNotOk 

• IDM::neverOk 


virtual Droplndicator Supported On: 

droplndicator() const; PM 

Returns the position of the pointing device. 


virtual IPoint 
position() const; 


Supported On: 

PM 


Exceptions 

IAccessError The pointing device’s position was not returned. The drag information is 

not accessible. 


setDefaultOperation 

Sets the default operation for the target. 


IDMTargetEnterEvent& Supported On: 

setDefaultOperation( unsigned long operation); PM 


setDropIndicator 

Sets the drop indicator which is one of the following: 

• IDMunotOk 

• IDMuok 
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• IDM::operationNotOk 

• IDM::neverOk 

Supported On: 

PM 


IDMTargetEnterEvent& 

setDropIndicator( Droplndicator indicator); 


Inherited Public Functions 


IDMTargetEvent 

presSpace 

releasePresSpace 



IE vent 
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operator = 
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Inherited Protected Data 
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This is the common base class for the direct manipulation target event classes, 
IDMTargetEnterEvent, IDMTargetLeaveEvent, and IDMTargetDropEvent. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMTargetEvent 

Use this function to construct an IDMTargetEvent from a generic IEvent (Vol. II) 
object. 

IDMTargetEvent( const IEvent& event); Supported On: 

PM 


"IDMTargetEvent 

This destmctor will release the drawing (presentation) space if you have not explicitly 
released it. 
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virtual 

"TDMTargetEvent (); 


Supported On: 

PM 


Target Emphasis 

Use these members to access and release the drawing space needed to draw target emphasis. 

Note: You must use the drawing (presentation) space returned by IDMTargetEvent::presSpace 
to draw the target emphasis. The drawing space returned by IWindow::presSpace will not work. 

-Acquires and returns the presentation space handle to use for drawing the target 
emphasis. 

virtual IPresSpaceHandle 
presSpace(); 


Exceptions 

IAccessError The presentation space was not obtained. An invalid window handle may 

have been specified or a direct manipulation is not in progress. 


Supported On: 

PM 


releasePresSpace 

Releases the presentation space handle that is used for drawing the target emphasis. 


virtual void 
releasePresSpace(); 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The presentation space was not released. An invalid presentation space 

may have been specified or a direct manipulation is not in progress. 


Inherited Public Functions 


IE vent 
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_.None. 
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Objects of the IDMTargetHandler class process events occurring on the target of a 
direct manipulation. You must add an object of this class to a window so it can 
support direct manipulation. This handler does not allow objects to be dragged from 
a window. See IDMSourceHandler (p. 460) for information about dragging objects 
from a window. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMTargetHandler 

[] IDMTargetHandler( IContai nerControl * contai nerControl); Supported On: 

PM 
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Use this function to create an object of this class by providing a pointer to a 
container. The constructed handler is automatically attached to the specified 
container. 

g IDMTargetHandl er ( IWindow* window); Supported On: 

PM 

Use this function to create an object of this class by providing a pointer to an 
IWindow object. The constructed handler is automatically attached to the specified 
window. 

2 IDMTargetHandl er( IEntryField* entryField); Supported On: 

PM 

Use this function to create an object of this class by providing a pointer to an entry 
field object. The constructed handler is automatically attached to the specified entry 
field. 

g IDMTargetHandl er( IMul ti Li neEdi t* mul ti LineEdi t); Supported On: 

PM 

Use this function to create an object of this class by providing a pointer to a 
multi-line edit (MLE) object. The constructed handler is automatically attached to the 
specified MLE. 

g IDMTargetHandl er(); Supported On: 

PM 


This is the default constructor. 

"IDMTargetHandler 


virtual 

'IDMTargetHandler(); 


Supported On: 

PM 


Renderer Processing 

These members override the rendering functions defined in the base IDMHandler class. Use 
them to access the IDMTargetRenderer objects involved in a direct manipulation. Objects of this 
class render the dragged objects that are compatible with the rendering mechanisms and formats 
that the User Interface Class Library supports. 

_.Adds the specified renderer to the set of candidates maintained by this handler and 
used to render objects dragged over a target window where this handler is attached. 

The renderer is added to the end of the renderer collection. 
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Note: Renderers are maintained by positions, which are 1-based. 


virtual IDMTargetHandl er& Supported On: 

addRenderer ( const IDMTargetRenderer& newRenderer); PM 

numberOfRenderers 

Returns the number of renderers associated with the target handler. 


virtual unsigned 
numberOfRenderers(); 


Supported On: 

PM 


removeRenderer 

Removes the specified tenderer from this target handler. 

Note: Renderers are maintained by positions, which are 1-based. 

virtual IDMTargetHandl er& Supported On: 

removeRenderer( const IDMTargetRenderer& rendererToRemove); PM 

Returns the Tenderer with the specified position. 

Note: Renderers are maintained by positions, which are 1-based. 


virtual IDMTargetRenderer* 
renderer( unsigned position); 


Supported On: 

PM 


replaceRenderer 

Replaces a given tenderer with another specified tenderer. 

Note: Renderers are maintained by positions, which are 1-based. 


virtual IDMTargetHandler& 
replaceRenderer( unsigned position, 

const IDMTargetRenderer& replacement); 


Supported On: 

PM 


_Sets the Tenderer for this handler. Removes any pre-existing renderers. 


virtual IDMTargetHandler& 

setRenderer( const IDMTargetRenderer& newRenderer); 


Supported On: 

PM 
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Inherited Public Functions 


IDMHandler 

defaultSourceHandler 

enableDragDropF or 

enableDropOn 

defaultTargetHandler 

enableDragF rom 

setDefaultSourceHandler 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

These members dispatch the various events for a direct manipulation target. 


dispatchHandlerEvent 

This function overrides of the default handler's dispatcher. It processes the direct 
manipulation events for the target. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM 


Event Processing 

These members are dispatched in response to specific direct manipulation events for the target. 
_Called when the dragged objects are dropped onto the target window. 


virtual Boolean 

targetDrop( IDMTargetDropEvent& event. 
Boolean container = true); 


Supported On: 

PM 
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..Called when the source tenderer completes rendering a specific drag item. The 
source Tenderer posts the target end event and this function process it. 

This function is not used by any of the default Tenderers supported by the User 
Interface Class Library. 

virtual Boolean Supported On: 

targetEnd( IDMTargetEndEvent& event); PM 

_Called when the dragged objects enter the target window. 


virtual Boolean Supported On: 

targetEnter( IDMTargetEnterEvent& event); PM 

..Called when the user requests help while dragging an object over the target window. 


virtual Boolean Supported On: 

targetHelp( IDMTargetHelpEvent& event); PM 

..Called when the dragged objects leave the target window. 


virtual Boolean 

targetLeave( IDMTargetLeaveEvent& event); 


Supported On: 

PM 


Implementation 

These members provide utilities used to implement this class. They are used by the User 
Interface Class Library. 


aliocateOperation 

Use this function to create a new IDMTargetOperation object. 

This function is called when the target handler is handling the processing of a new 
direct manipulation. Derived classes should override this function and return a class 
derived from IDMTargetOperation. 

Returns a handle to the target operation object. 

virtual IDMTargetOperation: :Handle Supported On: 

al locateOperation( IDMTargetEnterEvent& event) const; PM 
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findRendererFor 

Use this function to find the appropriate target Tenderer for the drag item. Returns 
the position of the Tenderer, or 0 if a Tenderer cannot be found. 

virtual unsigned Supported On: 

findRendererFor( const IDMItem: :Handle& item); PM 

findRenderersFor 

Use this function to find the appropriate target Tenderers for the specified target 
operation. 

virtual Boolean Supported On: 

findRenderersFor( const IDMTargetOperation::Handle& targetOperation); PM 


Inherited Protected Functions 



Inherited Protected Data 
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Objects of the IDMTargetHelpEvent class are sent to the target when help is 
requested while the objects are over the target. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMTargetHelpEvent 

Use this function to construct an IDMTargetHelpEvent from a generic IEvent (Vol. 

II) object. 

IDMTargetHel pEvent( const IEvent& event); Supported On: 

PM 


"IDMTargetHelpEvent 

virtual 

'IDMTargetHelpEvent (); 


Supported On: 

PM 


510 Open Class Library Reference 







IDMTargetHelpEvent 


Event Information 

Use these members to query event information for this class. 

-Returns the operation (for example, IDMOperation::move). Use this information to 
provide operation-specific help for the drag operation. 


virtual unsigned long 
operation() const; 


Supported On: 

PM 


Exceptions 

IAccessError The operation was not returned. The drag information is not accessible. 


Inherited Public Functions 
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IBase 

recoverable 

unrecoverable 



© IBM Corp. 1992, 1995 


IDMTargetHelpEvent 511 









IDMTargetLeaveEvent 



IDMTargetLeaveEvent 


IBase 
IVBase 
IEvent 
IDMEvent 
IDMTargetEvent 
IDMT argetLea veEvent 
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Objects of the IDMTargetLeaveEvent class are sent to the target when: 

• The user drags the objects out of the target. 

• The user terminates the drag while the objects are over the target. 

Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMTargetLeaveEvent 

Use this function to construct an IDMTargetLeaveEvent from a generic IEvent (Vol. 
II) object. 


IDMTargetLeaveEvent( const IEvent& event); 


Supported On: 

PM 
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IDMTargetLeaveEvent 


virtual 

"IDMTargetLeaveEventO ; 


Supported On: 

PM 


Inherited Public Functions 


IDMTargetEvent 
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Objects of the IDMTargetOperation class provide information about direct 
manipulation target operations. You can access this information through the static 
function IDMT argetOperation:: targetOperation. 

The target event handler class creates the objects of this class, not you, the 
application programmer. 

You can access an object of this class using IDMTargetOperation: :Handle which 
reference counts the object. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDMTargetOperation 

Use this function to create objects of this class by providing a reference to the target 
enter event. 
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IDMTargetOperation( 

IDMTargetEnterEvent& event); 

Supported On: 

PM 

Exceptions 

IAccessError 

The object for the target operation was not created, 
is not accessible. 

The drag information 

IlnvalidRequest 

The object for the target operation was not created, 
provider failed to provide any items. 

The target item 


IDMTargetOperation 

This destructor will enable the container refresh and refresh the container if a 
container is the target of the direct manipulation. 

virtual Supported On: 

~IDMTargetOperation(); PM 


Container Support 

Use these members to set and query container-specific attributes. 

Queries the current drop offset. The drop offset is the location where the next 
container object dropped would be positioned as long as the target operation's drop 
style is not IDM::dropPosition. The location is the offset relative to the position of 
the last object dropped. 

ISize Supported On: 

dropOffset() const; PM 

_ Returns the drop position for this item in container workspace coordinates, and sets 
the offset for the next item, according to the target operation's drop style. 

IPoi nt Supported On: 

dropPosition( const IDMItem: :Handle& dragltem, PM 

IDMTargetDropEvent& event); 

Returns true if the specified drop-style flag is set. 

Boolean 

isStyle( DropStyle dropStyle); 

positionRelativeTo 

Returns a drag item's position relative to the target container. If the drag item handle 
is 0, the drop point relative to the target container's origin is returned. 


Supported On: 

PM 
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IPoint 

positionRelativeTo( const IDMItem::Handle& item, 
IDMTargetDropEvent& event); 


Supported On: 

PM 


setDropOffset 

Sets the current drop offset in window coordinates. The drop offset is the location 
where the next container object dropped would be positioned as long as the target 
operation's drop style is not IDM::dropPosition. The location is the offset relative to 
the position of the last object dropped. 

IDMTargetOperation& Supported On: 

setDropOffset( const ISi ze& newPoi nterOffset); PM 

_Sets the drop style for the target operation. 

IDMTargetOperation& 
setStyle( DropStyle dropStyle); 

Returns the target operation's drop style 

DropStyle 
style() const; 

wasDragAfter 

Returns true if the target enter event was generated above the first list item, between 
list items, or after the last list item in one of the list views of a container. An 
example of a container list view is details view. 

Returns false if the event was generated over a list item. 

Bool ean Supported On: 

wasDragAfter() const; PM 


Supported On: 

PM 


Supported On: 

PM 


Implementation 

These members provide utilities used to implement this class. They are used by the User 
Interface Class Library. 

—Returns an IDMTargetOperation object. 

Note: Generally, you do not call this function. This function is called by an 
IDMTargetHandler object during the processing of a target enter event. 
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static IDMTargetOperation::Handle 
instanceFor( IDMTargetEnterEvent& event); 


Supported On: 

PM 


Exceptions 

IAccessError The handle for the target operation object was not returned. The drag 

information is not accessible. 


Operation Services 

Use these members for various operational services. 


setTargetOperation 

Sets an IDMTargetOperation handle during the initial target enter event. 


static void 
setTargetOperation ( 

IDMTargetOperation::Handle tgtOperation); 


Supported On: 

PM 


targetOperation 

Returns the IDMTargetOperation handle created during the initial target enter event. 


static IDMTargetOperation::Handle 
targetOperation(); 


Supported On: 

PM 


Inherited Public Functions 
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IRefCounted 

addRef 

removeRef 

useCount 
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Inherited Protected Functions 


IDMOperation 
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setDraglnfo 


Inherited Public Data 


IDMOperation 

copy 

drag 
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Inherited Protected Data 
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Nested Type Definitions 

typedef IReference < IDMTargetOperation > Handle; 

IDMTargetOperation: :Handle provides access to the IDMTargetOperation objects 
associated with a direct manipulation operation. Handle manages the references to 
the IDMTargetOperation object and ensures this object is not deleted until the direct 
manipulation operation is completed. 

Use Handle to reference a target operation handle within this class and 
IDMTargetOperation: :Handle externally. 

The handle provides a operator that enables instances to be treated just like 
pointers to an IDMTargetOperation object. 
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Objects of the IDMTargetRenderer class provide target rendering support for a direct 
manipulation. Objects of this class are registered with the target handler. The target 
handler selects a best match Tenderer for a given drag item by calling 
lDMTargetHandler::findRendererFor (p. 509). The target handler invokes the 
rendering functions of the selected Tenderer when the source or target rendering 
events occur. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IDMTargetRenderer 

Supported On: 

PM 


IDMTargetRenderer( const char* rmfs, 

const char* type = IDM::any); 
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Use this function to create objects of this class by providing rendering mechanisms 
and formats (RMFs) and types that indicate which drag item can be rendered by this 
target Tenderer. 

3 IDMTargetRenderer (); Supported On: 

PM 


This is the default constructor. 

When this constructor is used, the Tenderer supports any type and all of the default 
target RMFs supported by the User Interface Class Library: 

(TDM::rmLibrary)x(TDM::rfProcess,IDM::rfText,lDM::rfSharedMem), 

<IDM::rmFile,IDM::rfText> 

"IDMTargetRenderer 

virtual Supported On: 

'IDMTargetRenderer(); PM 


Source and Target Rendering 

Use these members to support the implementation of source or target rendering. 

- Returns an indication of the Tenderer's ability to render the item based upon the 
rendering mechanisms and formats associated with the item. 

Note: This function can be used for either source or target rendering, 
virtual Droplndicator 

canRender( const IDMItem::Handle& dragltem); 

informSourceOfCompletion 

Informs the source that the target has finished processing the data associated with the 
dropped item. The render completion code indicates if the target successfully 
processed the data or if it failed. 

Note: This function must be used for either source or target rendering. 

virtual IDMTargetRenderer& Supported On: 

informSourceOfCompletion( PM 

const IDMItem::Handle& dragltem, 

IDM::RenderCompletion code = IDM::targetSuccessful); 


Supported On: 

PM 
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Exceptions 

IlnvalidRequest The source could not be informed that the target finished processing. The 

drag item is invalid. 


supportsOperation 

Determines if the default operation, that is set by the source, is supported by the drag 
item. If the default operation is IDMOperation::drag, the target must select an 
operation. If no operation is selected, the User Interface Class Library’s default 
selection is IDMOperation::move, based upon Common User Access (CUA) 
guidelines. 

If the default operation defined by the source is >= IDMOperation:: unknown, the 
application must define the functionality of this operation and process the operation 
accordingly. 

When the default operation defined by the source is one of the following: 

IDMOperation: move 
IDMOperation: :copy 
IDMOperation: dink 

The default processing verifies if item supports the operation. 

Note: This function can be used for either source or target rendering. 

virtual Boolean Supported On: 

supportsOperation( const IDMItem::Handle& dragltem); PM 

_ Called when a drop event occurs for a drag item and the renderer must render the 
drag item. Use the rendering mechanism and format (RMF) to determine the type of 
rendering to implement. 

Note: This function can be used for either source or target rendering. 


virtual IDMTargetRenderer& Supported On: 

targetRender( IDMTargetDropEvent& event, PM 

const IDMItem::Handle& dragltem); 


Exceptions 

IlnvalidRequest 

The drag item was not rendered. The IDM::rfProcess rendering format can 
only be used if the source and the target are in the same process. 

IlnvalidRequest 

The drag item was not rendered. Source rendering of the drag item failed. 

IlnvalidRequest 

The drag item was not rendered. The rendering format is invalid. 

IlnvalidRequest 

The drag item was not rendered. The rendering mechanism is invalid. 
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targetRenderComplete 

Called when the source has completed the rendering of a drag item. This function is 
not used by any of the default Tenderers supported by the User Interface Class 
Library. 

Note: This function can be used for source rendering only. 

virtual IDMTargetRenderer& Supported On: 

targetRenderComplete( IDMTargetEndEvent& event); PM 

targetRenderPrepare 

Called when the source requests that the target generate a preparation event. 

Note: This function can be used for source rendering only. 


virtual IDMTargetRenderer& 
targetRenderPrepare( IDMTargetDropEvent& event, 

const IDMItem::Handle& dragltem); 


Supported On: 

PM 


Inherited Public Functions 


IDMRenderer 

defaultSourceRenderer 

setDefaultSourceRenderer 

setSupportedRMFs 

defaultTargetRenderer 

setDefaultT argetRenderer 

setSupportedTypes 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Renderer Specifics 

Use these members to process the different rendering operations that are specific to the supported 
rendering mechanisms and formats. 
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prepareAtSource 

Sends a source prepare event to the source to request source preparation for the 
specified drag item. The User Interface Class Library uses this function to implement 
the support for the <IDM::rmLibrary,IDM::rfSharedMem> rendering mechanism and 
format. 


virtual Boolean 

prepareAtSource( IDMTargetDropEvent& event, 

const IDMItem::Handle& dragltem); 


Supported On: 

PM 


render AtSource 

Sends a render event to the source to request source rendering for the specified drag 
item. The User Interface Class Library uses this function to implement the support 
for the <IDM::rmLibrary,IDM::rfSharedMem> rendering mechanism and format. 


virtual Boolean 

renderAtSource( IDMTargetDropEvent& event, 

const IDMItem::Handle& dragltem); 


Supported On: 

PM 


Exceptions 

IAccessError 

The render event was not sent to the source. The source window handle 
may be invalid. 

IOutOfMemory 

The render event was not sent to the source. The system was unable to 
allocate the required memory. 

IAccessError 

The render event was not sent to the source. The target process could not 
give the source process access to the shared memory buffer because the 
system may be out of memory or the buffer may be locked. 

IAccessError 

The render event was not sent to the source. The source reported an error 
during the processing of the source render event. 


renderComplete 

Called to process a completion event for the specified drag item. The User Interface 
Class Library uses this function to implement the support for the 
<IDM::rmLibrary,IDM::rfSharedMem> rendering mechanism and format. 


virtual Boolean 

renderComplete( const IDMItem::Handle& dragltem, 
void* pBuffer); 


Supported On: 

PM 


renderToName 

Provides the name of the location to which the data is rendered. This name could be 
a file name or a shared memory buffer. 
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virtual IString 

renderToName( const IDMItem::Handle& dragltem); 


Supported On: 

PM 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IDMTBarButtonltem 


IBase 

IVBase 

IRefCounted 

IDMItem 

IDMTBarButtonltem 


_.None. 


_Jdmtbbit.hpp 


Member 

Page 

Constructor 

526 

generateSourceltems 

528 

sourceDiscard 

527 

sourceToolBar 

527 

sourceT oolB arB utton 

527 


Member 

Page 

supportedOperationsFor 

528 

targetDrop 

526 

targetToolBar 

527 

targetToolB arB utton 

528 

'IDMTBarButtonltem 

526 


Objects of the IDMTBarButtonltem class are created by tool bars when tool bar 
buttons are moved. 

Objects of this class possess the following attributes (in addition to those inherited 
from its base class): 

• Association with a source drag operation object. 

• Association with IDM::rmLibrary rendering mechanism and IDM::rfProcess 
rendering format. 

This class provides virtual functions that implement direct manipulation support for 
tool bar buttons. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 
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IDMTBarButtonltem 

[J IDMTBarButtonItem( IDMSourceOperation* sourceOperation); Supported On: 

PM 

Use this constructor to construct items for the source of a direct manipulation. It 
accepts a pointer to the drag source operation. 

Q IDMTBarButtonItem( const IDMItem: :Handle& dragltem); Supported On: 

PM 


Use this constructor to construct items for the target of a direct manipulation. It 
accepts a handle to a generic drag item. 

The generic drag item is passed to IDMItemProviderFor::provideTargetItemFor of the 
target tool bar button’s drag item provider. 

IDMItemProviderFor::provideTargetItemFor uses the generic drag item to construct a 
tool bar button drag item by calling this constructor. 

"IDMTBarButtonltem 


virtual 

"TDMTBarBiittonltemO ; 


Supported On: 

PM 


Drop Processing 

Use these members during the drop operation of a direct manipulation. 

_.Use this function to process the drop of a drag item that represents a tool bar button 
object. This function processes the drop in the following manner: 

• If a tool bar button is dropped on another tool bar button, it is moved either 
before or after the tool bar button where the drop occurred. The positioning 
depends upon the location of the mouse pointer. If the mouse pointer is over the 
left-half or top-half of the target button, the button being dragged is moved 
before the target button. If it is over the middle, right-half, or bottom-half of the 
target button, the button being dragged is moved after the target button. 

• If the drag was initiated from a drop down menu, a new tool bar button is created 
based upon the bitmap, text, or bitmap and text in the drag object. The same 
positioning applies that is discussed in the previous paragraph. 

• If a bitmap file is dropped on a tool bar button, the button's bitmap is set using 
the bitmap stored within the bitmap file. 
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Derived classes should override this function when the default processing cannot be 
used. 


virtual Boolean 

targetDrop( IDMTargetDropEvent& event); 


Supported On: 

PM 


Shredder Support 

Use these members for tool bar button deletion when a tool bar button item is dropped on the 
system shredder. 

sourceDiscard 

Use this function to process a source discard event for a drag item that represents a 
tool bar button object. This function deletes the tool bar button object that is dropped 
on the system shredder. Derived classes should override this function when the 
default processing cannot be used. 

virtual Boolean Supported On: 

sourceDiscard( IDMSourceDiscardEvent& event); PM 


Source and Target Tool Bar 

Use these members to query the source and target tool bar and the tool bar buttons. 


sourceToolBar 

Returns the source tool bar where the drag was initiated. 


virtual IToolBar* Supported On: 

sourceTool Bar() const; PM 

sourceToolBarButton 

Returns the source tool bar button where the drag was initiated. 


virtual IToolBarButton* 

sourceToolBarButton() const; 


Supported On: 

PM 


targetToolBar 

Returns the target tool bar where the drop occurred. 


virtual IToolBar* 
targetToolBar() const; 


Supported On: 

PM 
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targetToolBarButton 

Returns the target tool bar button where the drop occurred. 


virtual IToolBarButton* 
targetToolBarButton() const; 


Supported On: 

PM 


Source Items 

Use these members to access and manipulate source items involved in a direct manipulation. 


generateSourceltems 

Use this function to generate a drag item that represents a tool bar button object. 

static Boolean Supported On: 

generateSourceltems( IDMSourceOperation* sourceOperation); PM 

Tool Bar Button Operations 

Use these members to set the supported direct manipulation operations for this class. 


supportedOperationsFor 

Returns operations this item supports using the specified rendering mechanism and 
format (RMF). If the specified RMF is <IDM::rmFile,IDM::rfText> the operation is 
set to IDMItem::copyable. Otherwise, the default operation is returned. 


virtual unsigned long 
supportedOperationsFor( 

const IString& selectedRMFs) const; 


Supported On: 

PM 


Inherited Public Functions 


IDMItem 

addRMF 

nativeRF 

setRequiresPreparation 

addType 

nativeRM 

setRMFs 

appendRMF 

nativeRMF 

setSelectedRMF 

attributes 

object 

setSourceName 

canBeCopied 

operator = 

setSourceW indo wHandle 

canBeLinked 

removeRMF 

setTargetName 

canBeMoved 

removeType 

setTrueType 
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IDMItem 

compressedRMF s 

Tenderer 

setTypes 

containerName 

requiresPreparation 

sourceDiscard 

contents 

rfF orThisProcess 

sourceEnd 

contentsSize 

rfFrom 

sourceltemFor 

deleteRMF 

rmfFrom 

sourceName 

dropStatus 

rmFrom 

sourceOperation 

enableCopy 

rmfs 

sourcePrepare 

enableLink 

rmfsFrom 

sourcePrint 

enableMove 

selectedRMF 

sourceRender 

generateSourceltems 

setContainer 

sourceWindow 

haslmage 

setContainerN ame 

sourceWindowHandle 

hasType 

setContents 

supportedOperations 

image 

setDropStatus 

supportedOperationsFor 

imageOffset 

setGroup 

supportsRMF 

isContainer 

setlmage 

targetDrop 

isGroup 

setNativeRMF 

targetEnd 

isOnRemovableMedia 

setObject 

targetName 

isOpen 

setOnRemovableMedia 

targetOperation 

isReference 

setOpen 

tokenForWPSObject 

isTargetTheSource 

setReference 

trueType 

matchingRMFs 

setRenderer 

types 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Functions 


IDMItem 

generateSourceName 




Inherited Public Data 


IDMItem 

container 

linkable 

open 

copyable 

moveable 

prepare 

group 

none 

reference 


Inherited Protected Data 


IDMItem 

strContents 




IBase 

recoverable 

unrecoverable 
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IDMToolBarltem 


IBase 

IVBase 

IRefCounted 

IDMItem 

IDMToolBarltem 


_.None. 

—idmtbrit.hpp 


Member Page 

Constructor 532 

targetDrop 532 

'IDMToolBarltem 532 


Objects of the IDMToolBarltem class are created by tool bars when a tool bar button 
or a menu item object is dropped on a tool bar. 

Objects of this class possess the following attributes (in addition to those inherited 
from its base class): 

• Association with a target drag operation object. 

• Association with IDM::rmLibrary rendering mechanism and !DM::rfProcess 
rendering format, or IDM::rmFile rendering mechanism and IDM::rfUnknown 
rendering format. 

This class provides virtual functions that implement direct manipulation support for 
tool bars. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 
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IDMToolBarltem 

Use this constructor to construct items for the target of a direct manipulation. It 
accepts a handle to a generic drag item. 

The generic drag item is passed to lDMItemProviderFor::provideTargetItemFor of the 
target tool bar’s drag item provider. lDMItemProviderFor::provideTargetItemFor uses 
the generic drag item to construct a tool bar drag item by calling this constructor. 

Note: Source items are not supported for this class. 

IDMToolBarltem( const IDMItem: :Handle& dragltem); Supported On: 

PM 


"IDMToolBarltem 

virtual 

'IDMToolBarltem(); 


Supported On: 

PM 


Drop Processing 

Use these members during the drop operation of a direct manipulation. 

_Use this function to process the drop of a drag item that represents a tool bar button 
or a menu item object. This function processes the drop in the following manner: 

• If the drag was initiated from a drop down menu, a new tool bar button is created 
based upon the bitmap, text, or bitmap and text in the drag object. The button is 
placed at the end of the tool bar. 

• If an existing tool bar button is dropped on a tool bar, it is treated as a move and 
is placed at the end of the tool bar. 

Derived classes should override this function when the default processing cannot be 
used. 

virtual Boolean Supported On: 

targetDrop( IDMTargetDropEvent& event); PM 


Inherited Public Functions 


IDMItem 

addRMF 

nativeRF 

setRequiresPreparation 

addType 

nativeRM 

setRMFs 
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IDMItem 

appendRMF 

nativeRMF 

setSelectedRMF 

attributes 

object 

setSourceName 

canBeCopied 

operator = 

setS ource Windo wHandle 

canBeLinked 

removeRMF 

setTargetName 

canBeMoved 

removeType 

setTrueType 

compressedRMF s 

Tenderer 

setTypes 

containerName 

requiresPreparation 

sourceDiscard 

contents 

rfF orThisProcess 

sourceEnd 

contentsSize 

rfFrom 

sourceltemFor 

deleteRMF 

rmfFrom 

sourceName 

dropStatus 

rmFrom 

sourceOperation 

enableCopy 

rmfs 

sourcePrepare 

enableLink 

rmfsFrom 

sourcePrint 

enableMove 

selectedRMF 

sourceRender 

generateSourceltems 

setContainer 

source Window 

haslmage 

setContainerName 

source Windo wHandle 

hasType 

setContents 

supportedOperations 

image 

setDropStatus 

supportedOperationsFor 

imageOffset 

setGroup 

supportsRMF 

isContainer 

setlmage 

targetDrop 

isGroup 

setNativeRMF 

targetEnd 

isOnRemovableMedia 

setObject 

targetName 

isOpen 

setOnRemovableMedia 

targetOperation 

isReference 

setOpen 

tokenForWPSObject 

isTargetTheSource 

setReference 

trueType 

matchingRMFs 

setRenderer 

types 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDMItem 

generate S ourceN ame 




Inherited Public Data 


IDMItem 

container 

linkable 

open 

copyable 

moveable 

prepare 

group 

none 

reference 


Inherited Protected Data 


IDMItem 

strContents 




IBase 

recoverable 

unrecoverable 
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IDrawingCanvas 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ICanvas 

IDrawingCanvas 


_.None. 


—idrawcv.hpp 

Member 

Page 

Constructor 

536 

calcMinimumSize 

539 

classDefaultStyle 

540 

con vertT oGUIS ty le 

538 

defaultStyle 

538 

graphicContext 

537 


Member 

Page 

graphicList 

537 

setDefaultStyle 

538 

setGraphicContext 

537 

setGraphicList 

538 

useDefaultPaintHandler 

540 

'IDrawingCanvas 

537 


The IDrawingCanvas class is a control class that provides support for drawing graphic 
objects. The drawing canvas contains an IGList to which you can add graphic 
objects. By default, a paint handler is attached to the drawing canvas. When paint 
events occur, the paint handler sets the clip region to the drawing canvas' update 
region and iterates through the IGList, redrawing the graphic objects necessary to 
update the window. If you do not add graphic objects to the IGList, the drawing 
canvas simply paints the window using the current background color. 

If you want to use your own paint handler instead of the drawing canvas' default 
paint handler, construct the IDrawingCanvas object without the 
useDefaultPaintHandler style. The default paint handler will not be attached to the 
drawing canvas. 

You have the option of setting the graphic context that the drawing canvas will use 
when drawing the graphic objects contained in the IGList object. By changing 
graphic contexts, you can change the appearance of the graphic objects or the device 
on which they are rendered. 
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To add graphic objects to a drawing canvas, create an IGList object and call 
setGraphicList. The drawing canvas iterates through the drawing canvas for its 
IGList. You can easily change the objects drawn in the drawing canvas by changing 
the IGList object. 

Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IDrawingCanvas 

You can construct objects of this class using the following parameter: 
windowldentifier 

Window identifier of the canvas you construct. 

Note: For OS/2, this value is limited to the range 0 through 65535. 

It is recommended that you: 

• Give unique identifiers to all windows in the same frame window. In 
the same window means that the frame window is the first frame in 
their parent window chain. 

• Give the client window a window ID of FID_CLIENT (0x8008). 

• Do not use the other FID_xxx values. 

parent The parent window of the canvas you construct. You must specify a 

parent window. This constructor throws an IlnvalidParameter exception 
if you pass an IWindow* of 0. The parent window is primarily used for 
visible relationships. 

owner The owner window of the canvas you construct. 

Note: In OS/2, the owner window is primarily used for routing 

notification events and unprocessed messages. OS/2 also uses the 
owner window chain to inherit colors. 

In Motif, the owner window is only used for routing unprocessed 
messages. There is no concept of an owner in Motif. 

initialSize (Optional) The initial position and size of the canvas you construct. The 
initial position is the lower-left corner of the canvas relative to the 
lower-left corner of the parent window. 

style (Optional) Use the styles provided by IDrawingCanvas (p. 540) Styles to 

specify the control’s styles. 
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IDrawingCanvas( unsigned long windowldentifier, Supported On: 

IWindow* parent, PM 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 


IDrawingCanvas 


virtual 

'IDrawingCanvas(); 


Supported On: 

PM 


Graphic Context 

Use these members to set and query the graphic context, which is used to paint the window when 
using the style IDrawingCanvas::useDefaultPaintHandler. If you do not set a graphic context, the 
default paint handler uses the graphic context that is provided from the paint event. See the class 
IGraphicContext (p. 720) for more details. 


graphicContext 

Returns a pointer to the graphic context that the drawing canvas uses for paint events. 
By default, the drawing canvas will uses the graphic context that is provided from the 
paint event. 

virtual IGraphicContext* Supported On: 

graphicContext() const; PM 


setGraphicContext 

Sets the graphic context that the drawing canvas uses when painting the window. 


virtual IDrawingCanvas& 

setGraphicContext( IGraphicContext* graphicContext); 


Supported On: 

PM 


Graphic List 

The graphic list is an ordered collection of graphic objects that is drawn when the drawing 
canvas receives a paint event. 

Use these members to set and query the graphic list object, which is drawn when the drawing 
canvas receives a paint event. The drawing canvas does not delete the graphic list when the 
drawing canvas is destroyed. 

-Returns a pointer to the IGList object set for the drawing canvas. 
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virtual IGList* 
graphicList() const; 


Supported On: 

PM 


setGraphicList 

Sets the IGList (p. 661) object that the drawing canvas draws when paint events 
occur. 


virtual IDrawingCanvas& 
setGraphicList( IGList* list); 


Supported On: 

PM 


Styles 

These style members provide valid styles for IDrawingCanvas::setDefaultStyle and for the 
constructor of the IDrawingCanvas (p. 535) class. 


convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

_ Returns the current default style, which is the same as classDefaultStyle unless 
setDefaultStyle has been called. 

static Style Supported On: 

defaultStyle(); PM 


setDefaultStyle 

Sets the default style for all subsequent drawing canvases. 

static void Supported On: 

setDefaultStyle( const Style& style); PM 
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Inherited Public Functions 


ICanvas 

backgroundColor 

defaultStyle 

origDefaultButtonHandle 

convertToGUIStyle 

isTabStop 

setDefaultStyle 

defaultPushButton 

matchForMnemonic 

setLay outDi storted 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Canvas Support 

These members override the inherited canvas-protected functions to provide layout support. 

calcMinimumSize 

Returns the minimum screen size this control can occupy, based on the size and 
positions of its child windows and graphic objects. 

virtual ISize Supported On: 

calcMinimumSize() const; PM 
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Inherited Protected Functions 


ICanvas 

areChildrenReversed 

layout 

registerCallbacks 

calcMinimumSize 

layoutSize 

setLay outSize 

fixupChildren 

passEventT oO wner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
Styles 

These style members provide valid styles for IDrawingCanvas::setDefaultStyle and for the 
constructor of the IDrawingCanvas (p. 535) class. 


classDefauitStyie 

Specifies the original default style for this class, which is 

IDrawingCanvas::useDefaultPaintHandler I IWindow::visible I IWindow::clipSiblings. 

static const Style Supported On: 

classDefauitStyie; PM 

useDefauitPaintHandler 

If this style is set, a default paint handler attaches to the drawing canvas. If this style 
is not set, you must handle window painting. 

static const Style Supported On: 

useDefauitPaintHandler; PM 


Inherited Public Data 


ICanvas 

classDefauitStyie 
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IWindow 

aetiveColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IDrawingCanvas contains the following nested classes: 
IDrawingCanvas::Style (see page 542) 
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IDrawingCanvas: :Style 


IBase 

IBitFlag 

IDrawingCanvas: :Style 


_.None. 

—idrawcv.hpp 

The nested class IDrawingCanvas::Style provides a set of valid styles for the 
IDrawingCanvas (p. 535) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



542 Open Class Library Reference 


























IFileDialog 



IFileDialog 


IBase 
IVBase 
INotifier 
IWindow 
IFrame W indo w 
IFileDialog 


_.None. 

_ifi led Ig. Iipp 


Member 

Page 

Member 

Page 

Constructor 

544 

multiSelection 

553 

apply Button 

552 

noStyle 

553 

buttonPressedld 

548 

ok 

551 

cancel 

551 

preload 

553 

classDefaultStyle 

552 

pressedOK 

548 

con vertT oGUIS ty le 

549 

registerCallbacks 

550 

defaultStyle 

549 

return Value 

548 

fileName 

547 

saveAsEAType 

547 

filter 

552 

selectableListbox 

553 

helpButton 

552 

selectedFileCount 

548 

includeEAS 

552 

setDefaultStyle 

549 

isModeless 

548 

unregisterCallbacks 

551 

modeless 

552 

“IFileDialog 

547 


Objects of the IFileDialog class display a file dialog for the user to choose a file. 
Once the user has chosen a file, you can use member functions of this class to 
retrieve information about the chosen file. You can use the following handlers to 
process the appropriate events for this control: 

• ICommandHandler (Vol. II) 

• IFileDialogHandler (p. 565) 

• IKeyboardHandler (Vol. II) 

• IMouseHandler (Vol. II) 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IFileDialog 
objects. 

IFileDialog 

| IFi1eDialog( IWindow* parent, 

IWindow* owner, 

IHandler* handler, 

const Style& style = defaultStyle ( ), 
const Settings& settings = Settings ( )); 

You can construct an object of this class by using this constructor which accepts a 
parent, owner, handler, style and settings as parameters. 

In order to add a IFileDialogHandler (p. 565) to a modal IFileDialog, you must 
specify the handler on the constructor. Once you create a modal IFileDialog, the 
dialog does not return control to the application until the user closes the dialog. At 
that time, it is too late to add a handler. 

The parameters for this constructor are the following: 

parent The parent of the dialog box. If you specify 0, the desktop becomes the 
parent of the dialog. 

owner The owner window. 

handler A pointer to an IHandler (Vol. II) object. 

style (Optional) Use the styles provided by IFileDialog (p. 551) to specify the 

style. The default creates a modal dialog. To construct a modeless 
dialog, specify the modeless style. 

settings (Optional) Use the settings provided by IFileDialog::Settings (p. 555) to 
specify the setting. 

IPM 

Note: In OS/2 Presentation Manager, you can have modal windows that do not use 
the desktop as their parent. However, Presentation Manager can change the 
owner window of your dialog to something other than what you specified to 
prevent your application from being hung. See the Presentation Manager 
Programming Reference Volume 2 for more information under WinLoadDlg. 


Supported On: 

PM, Motif 
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The easiest way to ensure that your dialog is modal is to use the desktop as 
the parent and an application window as the owner. Presentation Manager 
only disables the owner window and its child windows (the child windows of 
the child windows, and so forth) while a modal dialog is displayed. If you 
specify 0 for parent, the desktop automatically becomes the parent of the 
dialog. 

@ IFileDialog( IWindow* parent. Supported On: 

IWindow* owner, PM. Motif 

const Style& style = defaultStyle ( )); 

You can construct an object of this class by using this constructor which accepts a 

parent, owner, and style as parameters. 

The parameters for this constructor are the following: 

parent The parent of the dialog box. If you specify 0, the desktop becomes the 
parent of the dialog. 

owner The owner window. 

(Optional) Use the styles provided by IFileDialog (p. 551) to specify the 
style. The default creates a modal dialog. To construct a modeless 
dialog, specify the modeless style. 


In OS/2 Presentation Manager, you can have modal windows that do not use 
the desktop as their parent. However, Presentation Manager can change the 
owner window of your dialog to something other than what you specified to 
prevent your application from being hung. See the Presentation Manager 
Programming Reference Volume 2 for more information under WinLoadDlg. 

The easiest way to ensure that your dialog is modal is to use the desktop as 
the parent and an application window as the owner. Presentation Manager 
only disables the owner window and its child windows (the child windows of 
the child windows, and so forth) while a modal dialog is displayed. If you 
specify 0 for parent, the desktop automatically becomes the parent of the 
dialog. 

g IFi1eDialog( IWindow* parent, 

IWindow* owner, 
const Settings& settings, 
const Style& style = defaultStyle ( )); 

You can construct an object of this class by using this constructor which accepts a 
parent, owner, settings and style as parameters. 


Supported On: 

PM, Motif 


style 

IPM 

Note: 
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The parameters for this constructor are the following: 

parent The parent of the dialog box. If you specify 0, the desktop becomes the 
parent of the dialog. 

owner The owner window. 

settings Use the settings provided by IFileDialog::Settings (p. 555) to specify the 
setting. 

style (Optional) Use the styles provided by IFileDialog (p. 551) to specify the 

style. The default creates a modal dialog. To construct a modeless 
dialog, specify the modeless style. 

IPM 

Note: In OS/2 Presentation Manager, you can have modal windows that do not use 
the desktop as their parent. However, Presentation Manager can change the 
owner window of your dialog to something other than what you specified to 
prevent your application from being hung. See the Presentation Manager 
Programming Reference Volume 2 for more information under WinLoadDlg. 

The easiest way to ensure that your dialog is modal is to use the desktop as 
the parent and an application window as the owner. Presentation Manager 
only disables the owner window and its child windows (the child windows of 
the child windows, and so forth) while a modal dialog is displayed. If you 
specify 0 for parent , the desktop automatically becomes the parent of the 
dialog. 

jj] IFi 1 eDialog( IWindow* parent, 

IWindow* owner, 
const Style& style, 
const Settings& settings); 

You can construct an object of this class by using this constructor which accepts a 

parent, owner, style and settings as parameters. 

The parameters for this constructor are the following: 

parent The parent of the dialog box. If you specify 0, the desktop becomes the 
parent of the dialog. 

owner The owner window. 

style Use the styles provided by IFileDialog (p. 551) to specify the style. The 

default creates a modal dialog. To construct a modeless dialog, specify 
the modeless style. 


Supported On: 

PM, Motif 
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settings Use the settings provided by IFileDialog: :Settings (p. 555) to specify the 
setting. 

IPM 

Note: In OS/2 Presentation Manager, you can have modal windows that do not use 
the desktop as their parent. However, Presentation Manager can change the 
owner window of your dialog to something other than what you specified to 
prevent your application from being hung. See the Presentation Manager 
Programming Reference Volume 2 for more information under WinLoadDlg. 

The easiest way to ensure that your dialog is modal is to use the desktop as 
the parent and an application window as the owner. Presentation Manager 
only disables the owner window and its child windows (the child windows of 
the child windows, and so forth) while a modal dialog is displayed. If you 
specify 0 for parent , the desktop automatically becomes the parent of the 
dialog. 


IFileDialog 


virtual Supported On: 

"IFileDialogO; PM, Motif 

Getting Information about the Chosen File 

Use these members to get information about the file that was selected in the file dialog. 

__ Returns the fully qualified file name selected by the user. 

fileNumber The number indicating which file name you want. The default is 0. 

When you specify the style multiSelection (p. 553) for your IFileDialog 
object, set fileNumber to selectedFileCount (p. 548) minus 1 to ensure the 
correct number of files is returned. 


IString Supported On: 

fileName( unsigned fileNumber = 0) const; PM, Motif 


saveAsEAType 

Returns the extended attribute (EA) for a Save As dialog. This is the type the user 
chose from the drop-down list box of EA types. If the user chose the EA type <A11 
Files>, a 0-length IString is returned. 


IString 

saveAsEAType() const; 

f_i This function always returns an empty string. 


Supported On: 

PM, Motif 
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selectedFileCount 

Returns the number of files selected by the user. 

Note: If you create the dialog with the style multiSelection (p. 553), this number can 
be more than 1. 

unsigned Supported On: 

selectedFileCount() const; PM, Motif 


Getting Information about the Dialog 

Use these members to get specific information about the dialog. 


buttonPressedld 

Returns the ID of the push button used to close the dialog. 


unsigned long Supported On: 

buttonPressedId() const; PM. Motif 

_If this is a modeless dialog, true is returned. 


Boolean Supported On: 

isModeless() const; PM. Motif 

_If the user ends the dialog by selecting the OK push button, true is returned. 


Bool ean Supported On: 

pressedOK() const; PM. Motif 

... It an error occurs, the return code is returned, 
long 

returnValue() const; 

IPM The return value is an FDS_ERR system return code 
tells the application the reason for the failure. 

IMotifl This function always returns 0. 

Styles 

These style members provide a set of valid file dialog styles for the IFileDialog::setDefaultStyle 
function and for the constructors of the IFileDialog (p. 543) class. 


Supported On: 

PM. Motif 

. When a dialog fails, this value 
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convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

- Returns the default style. The default style is classDefaultStyle (p. 552) unless you 
changed the style using setDefaultStyle (p. 549). 


static Style 
defaultStyle(); 


Supported On: 

PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent file dialogs. 

style Dialog style. Use the styles provided by IFileDialog (p. 551) to specify 

the default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IFrameWindow 

addExtension 

isFlashing 

setBorderWidth 

addToWindowList 

isMaximized 

setClient 

backgroundColor 

isMinimized 

setDefaultOrdering 

beginFlashing 

isModal 

setDefaultStyle 

borderHeight 

maximize 

setDestroyOnClose 

borderS ize 

maximizeRect 

setExtensionSize 

borderWidth 

minimize 

setlcon 

client 

minimizeRect 

setLay outDi storted 

clientHandle 

mousePointer 

setMousePointer 

clientRectFor 

moveS izeToClient 

setRestoreRect 

close 

nextShellReet 

setResult 
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IF rameWindow 

convertToGUIStyle 

notifyOwner 

setToolBarList 

defaultOrdering 

removeExtension 

shareParentDBCSStatus 

defaultStyle 

remo veFromW indo wList 

show 

disabledBackgroundColor 

resetBackgroundColor 

showModally 

dismiss 

resetDisabledBackgroundColor 

start 

enableNotification 

restore 

toolBarList 

endFlashing 

restoreRect 

topHandle 

frameRectFor 

result 

update 

handleFor 

setBorderHeight 

useExtensionMinimumSize 

icon 

setBorderSize 

usesDialogBackground 


INotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Overrides 

These members override of base class members used to implement this class. 

registerCallbacks 

Adds callbacks and X event handlers to this IFileDialog for events it might receive. 
This function adds all possible callbacks and X event handlers. IHandler derived 
classes later determine which events they process. 

virtual void Supported On: 

registerCal 1 backs (); Motif 
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unregisterCallbacks 

Removes callbacks and X event handlers from this IFileDialog which were added by 
registerCallbacks (p. 550). 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Inherited Protected Functions 


IFrameWindow 

addDefaultHandler 

findExtensions 

registerFrameClass 

attachClient 

initialize 

removeDefaultHandler 

create 

isFrameWindow 

setExtensions 

extensions 

isRelatedHandle 

tryToLoadDialog 

findExtension 

registerCallbacks 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 

Getting Information about the Dialog 

Use these members to get specific information about the dialog. 

Push button ID value returned when the dialog is dismissed by pressing the Cancel 
button. 

static const unsigned long Supported On: 

cancel; PM, Motif 

Push button ID value returned when the dialog is dismissed by pressing the OK 
button. 


static const unsigned long Supported On: 

ok; PM. Motif 
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Styles 

These style members provide a set of valid file dialog styles for the IFileDialog::setDefaultStyle 
function and for the constructors of the IFileDialog (p. 543) class. 

-..Adds an Apply push button to the dialog. This is useful in a modeless dialog. 

static const Style Supported On: 

applyButton; PM. Motif 

classDefaultStyle 

Specifies the original default style for this class, which is noStyle. This style results 
in a modal open dialog. 


static const Style Supported On: 

classDefaultStyle; PM. Motif 

.. Specifies that the dialog use the union of the string filter and the extended-attribute 
type filter when filtering files for the Files list box. When you do not specify this 
style, the list box uses the intersection of the two by default. 

static const Style Supported On: 

filter; PM, Motif 

_Adds a Help push button to the dialog. This push button sends a help message to 
the owner of the dialog. 


static const Style Supported On: 

hel pButton; PM, Motif 

—Specifies that the dialog always queries the extended attribute information for files 
as it fills the Files list box. The default is to not query the information, unless the 
user selects an extended-attribute type filter from the dialog. 


static const Style Supported On: 

incl udeEAS; PM, Motif 

-.Specifies that the dialog is modeless. The constructor for a modeless dialog returns 
immediately. To determine which files were chosen by the user, create an 
IFileDialogHandler and use IFileDialogHandler::modelessResults (p. 568). 


static const Style 
model ess; 


Supported On: 

PM, Motif 
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multiSelection 

Specifies that the Files list box for the dialog is a multiple-selection list box. If you 
do not specify this style, the default is a single-selection list box. 

static const Style Supported On: 

multiSelection; PM, Motif 

Disables all of the valid styles. Use this style only when you are not using any 
other styles. 

static const Style 
noStyle; 

.Specifies that the dialog do the following: 

• Preload the volume information for the drives 

• Preset the current default directory for each drive 

By default, the volume label is blank and the initial directory is the root directory for 
each drive. 

Note: This is not done by default because of potential delays in retrieving this 

information, which can be caused by network delays (for network drives) or 
hardware timeouts due to unavailable media. 

static const Style 
preload; 

selectableListbox 

Enables the Files list box on a Save As dialog. If you do not specify this style, it 
disables the Files list box for a Save As dialog. Disabling is the default. 

static const Style Supported On: 

sel ectabl eLi stbox; PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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IWindow 

backgroundColorld 

enableld 

inactiveColorld 

borderColorld 

focusld 

positionld 

commandld 

fontld 

shadowColorld 

deleteld 

foregroundColorld 

sizeld 

disabledBackgroundColorld 

hiliteBackgroundCoIorld 

systemCommandld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IFileDialog contains the following nested classes: 

IFileDialog::Settings (see page 555) 
IFileDialog::Style (see page 561) 
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IFileDialog::Settings 


IBase 

IFileDialog:: Settings 


_„None. 




_.ifiledlg.hpp 




Member 

Page 

Member 

Page 

Constructor 

556 

setFileName 

559 

addDrive 

558 

setlnitialDrive 

559 

addFileType 

558 

setlnitialFileType 

559 

fileName 

558 

setOKButtonText 

557 

initialDrive 

558 

setOpenDialog 

559 

initialFileType 

558 

setPosition 

557 

isDialogTemplateSet 

556 

setS ave AsDialog 

560 

isOpenDialog 

558 

Settings 

556 

isPositionSet 

556 

setTitle 

557 

okButtonText 

556 

title 

558 

position 

556 

“Settings 

556 

setDialogTemplate 

557 




Objects of the IFileDialog::Settings class contain input for an IFileDialog (p. 543) 
object. If you do not specify a Settings object on the IFileDialog constructor, a 
default Settings object is created for you. This default object provides an open dialog 
with no other settings in effect. 

You can pass the following information within an IFileDialog::Settings object to an 
IFileDialog: 

• The dialog's title 

• The text to appear on the OK push button 

• The position of the dialog 

• Whether the dialog is an Open or Save As dialog 

• An initial file specification 

IPM You can also specify the following items within a Settings object: 

• An initial file type extended attribute 

• An initial drive specification 

• A dialog template to use in place of the system default 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 

_You can only construct objects of this class by using the default constructor, which 
accepts no parameters. 

Settings (); Supported On: 

PM. Motif 


Settings 


'Settings (); 


Supported On: 

PM. Motif 


Dialog Customization 

Use these members to customize the file dialog presented to the user. The file dialog includes 
the dialog's title, OK button's text, dialog position and the dialog template to use. 

isDialogTemplateSet 

Returns true if the dialog template was set. 


Bool ean Supported On: 

isDialogTemplateSet() const; PM. Motif 

--Returns true if the dialog position was set. 


Boolean 

isPositionSet() const; 


Supported On: 

PM. Motif 


okButtonText 

Returns the text of the OK button. 


IString Supported On: 

okButtonText() const; PM, Motif 

Returns the initial placement of the dialog within the parent window. 
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I Point Supported On: 

position() const; PM, Motif 

setDialogTemplate 

Sets a dialog template resource to use in place of the OS/2-supplied default file 
dialog. 

resld The resource ID of the dialog template to use. 


Settings& Supported On: 

setDialogTemplate( const IResourceId& resld); PM 

setOKButtonText 

Sets the text that appears on the OK push button. 

newText A character string to appear on the OK push button. 

resld The resource ID of a string to appear on the OK push button. 


B Settings& 

setOKButtonText( const char* newText); 


Supported On: 

PM, Motif 


B Settings& Supported On: 

setOKButtonText( const IResourceId& resld); PM, Motif 

_..Sets the initial placement of the dialog within the parent window. 

position The initial position for the dialog. 


Settings& Supported On: 

setPosition( const IPoint& position); PM, Motif 

Sets the dialog's title. The parameters are the following: 

newTitle A character string to use as the dialog title. 

resld The resource ID of a string to use as the dialog title. 


Q Settings& 

setTitle( const char* newTitle); 


Supported On: 

PM, Motif 
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5 Settings& 

setTitle( const IResourceId& resld); 
Returns the dialog's title. 


Supported On: 

PM. Motif 


IString 

title() const; 


Supported On: 

PM. Motif 


Setting Information about the Initial Dialog 

Use these members to set and query the initial information that appears in the dialog. 

Adds a drive or network identifier to the Drive list in the initial dialog. If you call 
this function, the Drive list is limited to the drives you specify in drive. 

drive The drive or network identifier to add to the Drive list. 


Settings& Supported On: 

addDrive( const char* drive); PM, Motif Ignored 

_Adds the specified type to the drop-down list box of extended-attribute types. 

fdeType The extended-attribute type to add. 


Supported On: 

PM, Motif Ignored 

Returns the default file name selection. 


Settings& 

addFileType( const char* fileType); 


IString Supported On: 

fileName() const; PM, Motif 

^Returns the drive for which initial information is displayed. 


IString 

initialDrive() const; 


Supported On: 

PM, Motif 


initialFileType 

Returns the file type that is used to filter the initial list of files. 


IString Supported On: 

initial FileTypeO const; PM, Motif 

—Returns true if dialog is an open dialog. 
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Boolean Supported On: 

isOpenDialog() const; PM, Motif 

_Sets a default file name selection. 

fileName The file name to use as the default. If you want to specify wildcard 
characters or path information for the dialog defaults, include this 
information in this parameter's string. If you do not specify the path with 
the file name, the current directory is used. 

Settings& Supported On: 

setFileName( const char* fileName); PM, Motif 


setlnitialDrive 

Sets the drive for which initial information is displayed. If you do not call this 
function, the dialog displays the information for the current drive. If you specify a 
drive for this function, you do not have to specify it again when calling addDrive (p. 
558). 

drive The initial drive to display. 


Settings& 

set InitialDrive( const char* drive); 


Supported On: 

PM, Motif Ignored 


setlnitialFileType 

Sets the extended attribute that filters the initial display of files. If you do not call 
this function, the default is <A11 Files>. If you specify a type for this function, you 
do not have to specify it again when calling addFileType (p. 558). 

fileType The initial extended attribute. 


Settings& 

set InitialFileType( const char* fileType); 


Supported On: 

PM, Motif Ignored 


setOpenDialog 

Creates an Open File dialog. An Open File dialog has the list of files enabled for 
selection, while a Save As dialog has this list disabled. An Open File dialog is the 
default. 


Settings& 

setOpenDialog(); 


Supported On: 

PM, Motif 
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setSaveAsDialog 

Creates a Save As dialog. An Open File dialog is the default. By default, an Open 
File dialog has the list of files enabled for selection, while a Save As dialog has this 
list disabled. You can use the style IFileDialog::selectableListbox (p. 553) to force 
the list of files to be selectable on a Save As dialog. 

Settings& Supported On: 

setSaveAsDi al og (); PM. Motif 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFileDialog: :Style 


IBase 

IBitFlag 

IFileDialog: :Style 


_None. 

...ifiledlg.hpp 

The nested class IFileDialog::Style provides a set of valid styles for the IFileDialog 
(p. 543) class. 

|_ For the AIX release, applyButton does not add the Apply push button to the dialog. 

Instead, this style specifies that the dialog not be dismissed when the user presses the 
OK push button. 

The AIX release ignores the following styles: 

• filter 

• includeEAS 

• preload 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 
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IFileDialog::Style 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFileDialogEvent 


IBase 

IVBase 

IEvent 

IFileDialogEvent 


_.None. 


_ ifilehdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

563 

fileName 

564 

fileLength 

564 

“IFileDialogEvent 

563 


Objects of the IFileDialogEvent class encapsulate events used in an 
IFileDialogHandler (p. 565) object. It provides the name and length of the file that 
the event pertains to. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IFileDialogEvent 

Although you can construct objects of this class, typically 

IFileDialogHandler::dispatchHandlerEvent (p. 567) creates objects of this class from 
an object of the class IEvent (Vol. II). 

IFileDialogEvent( IEvent& event); Supported On: 

PM, Motif 


"IFileDialogEvent 


virtual 

"IFileDialogEvent(); 


Supported On: 

PM, Motif 
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File Name Accessors 

Use these members to retrieve information about the event. 

..Returns the length of the file name the event pertains to. 


unsigned long Supported On: 

fileLength() const; PM. Motif 

Returns the file name the event pertains to. 


IString 

fileName() const; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFileDialogHandler 


IBase 

IVBase 

IHandler 

IFileDialogHandler 


_.None. 


__ifilehdr.hpp 


Member 

Page 

Constructor 

566 

dispatchHandlerEvent 

567 

filter 

568 

filterName 

568 

handleEventsFor 

566 


Member 

Page 

modelessResults 

568 

stopHandlingEventsFor 

566 

validate 

568 

validateName 

569 

“IFileDialogHandler 

566 


Objects of the IFileDialogHandler class handle the various events that affect the file 
dialog. 

You can create a handler derived from IFileDialogHandler and attach it to a file 
dialog. Do this by calling IHandler::handleEventsFor (Vol. II) to pass the appropriate 
file dialog to the file dialog handler. 

Note: To add a handler to a modal file dialog, you must specify a pointer to the 

handler using the IFileDialog constructor (p. 543) that accepts such a pointer 
as one of its parameters. 

When the file dialog handler receives a file dialog event, it creates an 
IFileDialogEvent (p. 563) object and routes that object to the appropriate 
IFileDialogHandler virtual function. You can override these virtual functions to 
supply your own specialized processing of a file dialog event. 

The return value from the virtual functions specifies whether the file dialog event is 
passed on for additional processing, as follows: 

true The file dialog event requires no additional processing. Do not pass it to 
another handler. 
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false Pass the file dialog event to the next handler for additional processing, as 
follows: 

• If there is another handler for the file dialog, pass the file dialog event 
to the next handler. 

• If this is the last handler for the file dialog, call 
IWindow::defaultProcedure (Vol. II) to process the file dialog event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IFileDialogHandler 

You can only construct objects of this class using the default constructor, which does 
not accept any parameters. 

IFileDialogHandlerQ; Supported On: 

PM. Motif 


"IFileDialogHandler 


virtual 

''IFileDialogHandlerO; 


Supported On: 

PM. Motif 


Window Attachment 

Use these members to attach handler object to and detach it from a file dialog window. 

handleEventsFor 

Attaches the handler to the specified file dialog passed in the argument. 


virtual IFileDialogHandler& 
handleEventsFor( IFileDialog* fileDialog); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidParameter A NULL pointer was passed instead of a valid IFileDialog*. 


stopHandlingEventsFor 

Detaches the handler from the specified file dialog passed in the argument. 
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virtual IFileDialogHandler& 

stopHandlingEventsFor( IFileDialog* fileDialog); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter A NULL pointer was passed instead of a valid IFileDialog*. 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Dispatch Events 

These members determine if the event is one of the file dialog events. If it is, it calls the 
appropriate virtual function. 

dispatchHandlerEvent 

If a file dialog event is received, the appropriate virtual function is called. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


File Dialog Events 

These members are called when a file dialog event occurs. Override these to provide your own 
processing. 
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..Lets you determine which file names appear in the list box. Use 
IFileDialogEvent::fileName (p. 564) to determine the file that is about to be added to 
the dialog's file list box. If you do not want the file to appear in the list box, call 
IEvent::setResult(false) (Vol. II). If you do not want the event to be processed by 
any other handlers, return true. 

virtual Boolean Supported On: 

fi 1 ter( IFileDialogEvent& event); PM. Motif 

^Override this function to supply an easier way of filtering files. The supplied 
default function returns true. If you do not override it, nothing is filtered. If you do 
not want fileName to appear in the dialog, return false. 

file Name The name of the file you want to filter. 

dialog File dialog pointer. If you need to access the IFileDialog object itself, 
you can use the IFileDialog* (p. 543) pointer. 

virtual Boolean Supported On: 

filterName( const IString& fileName, PM. Motif 

IFileDialog* dialog); 


modelessResults 

Called when a modeless dialog is closed, even if the dialog is cancelled. This is done 
so that you can destroy the IFileDialog (p. 543), if needed. Use 
IFileDialog::pressedOK (p. 548) to determine whether the user ended the dialog by 
pressing the OK push button. 

If you need to destroy the IFileDialog object, do not delete the IFileDialog* pointer 
from within modelessResults. Instead, use the following: 

endingDialog->setAutoDeleteObject(True) 


virtual Boolean Supported On: 

model essResul ts ( IFileDialog* endi ngDi al og); PM. Motif 

.. Called when a user selects a file and presses Enter or double-clicks on a file in the 
list box. Use IFileDialogEvent::fileName (p. 564) to get the name selected by the 
user. If the name is unacceptable, call IEvent::setResult(false) (Vol. II). In this case, 
the dialog is not ended. If you do not want the event to be processed by any other 
handlers, return true. 


virtual Boolean 

validate( IFileDialogEvent& event); 


Supported On: 

PM. Motif 
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—Override this function to supply an easier way of validating. The supplied default 
function returns true, so that if you do not override it, nothing is validated. If 
fileName is unacceptable, return false. 

fileName The name of the file you want to validate. 

dialog If you want to inform the user why you rejected the name, use the 
IFileDialog* pointer in an IMessageBox (Vol. II) constructor. 


virtual Boolean 

validateName( const IString& fileName, 
IFileDialog* dialog); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFIyOverHelpHandler 


IBase 

IVBase 

IHandler 

IFlyOverHelpHandler 


_.None. 

_i II y h h tl i. h p p 


Member 

Page 

Member 

Page 

Constructor 

572 

resourceLibrary 

575 

defaultText 

575 

setDefaultText 

576 

delayTime 

577 

setDelayTime 

578 

dispatchHandlerEvent 

579 

setFlyT extControl 

574 

flyHelpText 

573 

setFlyT extS tringT ableOff set 

577 

flyTextControl 

574 

setHelpText 

573 

AyTextStringTableOffset 

577 

setlnitialDelayTime 

578 

handleEventsFor 

574 

setLongStringTableOffset 

577 

initialDelayTime 

578 

setLongTextControl 

575 

longHelpText 

573 

setResourceLibrary 

575 

longStringT ableOff set 

577 

stopHandlingEventsFor 

574 

longT extControl 

574 

'IFlyOverHelpHandler 

573 

removeHelpText 

573 




Objects of this class display context-specific help for windows that the mouse is over. 
By attaching an IFlyOverHelpHandler to a window, you can provide context-specific 
help messages for the window that you attached the handler to and any of its 
descendent windows. 

You can use the IFlyOverHelpHandler to update an IFlyText control, an ITextControl, 
or both. Use the IFlyText control to display brief informative messages for a 
window, such as the function of a push button contained in a tool bar. The 
ITextControl should be used to display longer, more informative text like that found 
in an information area of a frame window. Typically, you will not have a string 
associated with every window in your application. When a help string cannot be 
found for a window, you can set "missing" text you would like displayed in the 
ITextControl. By default, a single blank is displayed in the ITextControl to avoid the 
frame extension handler from hiding the ITextControl when it contains a null string. 
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Note: It is often convenient to use the same string table identifier for the text of a 
control and the text that is displayed in the IFlyText control. You can have 
the control text span multiple lines by having a new line character in the 
string. While the new line is desirable for the control text, it is not desirable 
for the IFlyText control. For this reason, new line characters are removed 
from a string before they are displayed in the IFlyText control. 

The last two parameters of each constructor specify time delays expressed in 
milliseconds. The first delay indicates an initial delay that the mouse must remain in 
the same location for the first time fly over help is displayed for a window. The 
second delay indicates the time the mouse must remain in the same location after the 
first time fly over help has been displayed. For example, the first time fly over help 
is displayed, you may want to set the initial delay to two seconds. Then you may 
want to set the second delay to one-half second. 

The primary method of associating context-specific help for a window to a help 
message is by a window identifier as is the case for IlnfoArea. The window 
identifier, in conjunction with an offset that is added to the window identifier, is used 
to load strings from a string table. You can specify different offsets into the string 
table for the IFlyText and the ITextControl objects thereby allowing you to display 
different help messages for a window in each of the controls. 

Note: To display help for a window via a string table in a resource file based on the 
windows identifier, you must either create the window via the class library or 
wrapper an existing window. 

In addition to loading help text via a string table in a resource file, you can also 
dynamically associate help text to a window. This association is made using window 
handles. This is useful if you dynamically add controls to a canvas or push buttons 
to a tool bar. If you dynamically add help text to a window, this takes precedence 
over help that is otherwise loaded from a string table. 
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Efx Tool Bar Sample 1 

1 0 □ 

Edit Toolbar 


a b i u 

Y 

This is fly over help 

V 

Removes the marked text and places it on the clipboard. 


Figure 3. Fly Over Help 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

Note: Each constructor's last two parameters are optional. These parameters are delay times 

expressed in milliseconds. The first delay indicates an initial delay that the mouse must 
remain in the same location for the first time fly over help is displayed for a window. 

The second delay indicates the time the mouse must remain in the same location after the 
first time fly over help has been displayed. 

IFlyOverHelpHandler 

[J IFlyOverHelpHandler( IFlyText* flyText, Supported On: 

unsigned long initial Del ay = 100, PM 

unsigned long delay = 100); 

Use this function to construct object of the IFlyOverHelpHandler class from a 
IFlyText object and optionally an initial delay and delay time in milliseconds. The 
IFlyText control should be used to display brief help messages. 

g IFlyOverHelpHandler( ITextControl* longText, Supported On: 

unsigned long initial Del ay = 100, PM 

unsigned long delay = 100); 

Use this function to construct objects of the IFlyOverHelpHandler class from a 
ITextControl object. Typically, you display longer, more informative help messages 
for the window the mouse is over. 
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2 IFlyOverHelpHandler( IFlyText* flyText, Supported On: 

ITextControl * longText, PM 

unsigned long initialDelay = 100, 
unsigned long delay = 100); 

Use this function to construct an object of the IFlyOverHelpHandler class from a 
IFlyText object and a ITextControl object. 

"IFlyOverHelpHandler 


virtual 

"IFlyOverHelpHandlerO ; 


Supported On: 

PM 


Dynamically Updating Help Text 

These members dynamically add help text to or removed it from a window. If you add help text 
to a window by the setHelpText functions, this text takes precedence over text that would 
otherwise be loaded from a string table. 

_Retums the short help text for a window if you have dynamically added help text 
for the window. 


virtual IString Supported On: 

flyHelpText( const IWindowHandl e& handle) const; PM 

—Returns the long help text for a window if you have dynamically added long help 
text for the window. 


virtual IString 

longHelpText( const IWindowHandle& handle) const; 


Supported On: 

PM 


removeHelpText 

Removes help text added to a window using setHelpText. 

virtual IFlyOverHelpHandler& Supported On: 

removeHelpText( const IWindowHandl e& handle); PM 

— Sets the help text for a window by specifying a string or resource identifier. 


Q virtual IFlyOverHelpHandler& Supported On: 

setHelpText( const IWindowHandl e& handle, PM 

const IString& flyText, 
const IString& longText = IString ( )); 
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virtual IFlyOverHelpHandler& 
setHelpText( const IWindowHandl e& handle, 
const IResourceId& flyText, 
const IResourceId& longText); 


Supported On: 

PM 


Event Dispatching 

Event-dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process. 


handleEventsFor 

Attaches the handler to the specified window passed in the argument. 

virtual IFlyOverHelpHandler& Supported On: 

handleEventsFor( IWindow* window); PM 

stopHandlingEventsFor 

Detaches the handler from the specified window passed in the argument. 


virtual IFlyOverHelpHandler& 
stopHandlingEventsFor( IWindow* window); 


Supported On: 

PM 


Quering and Setting Text Controls 

Use these members to query and set the text controls that display help text. 


flyTextControl 

Returns a pointer to the fly text control that is used to display fly help text. 


virtual IFlyText* 
flyTextControl() const; 


Supported On: 

PM 


longTextControl 

Returns a pointer to the text control that is used to display long help text. 

virtual ITextControl* Supported On: 

longTextControl () const; PM 

setFlyTextControl 

Sets the control to use to display fly help text. 
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virtual IFlyOverHelpHandler& Supported On: 

setFlyTextControl ( IFlyText* flyText); PM 


setLongTextControl 

Sets the control to use to display long help text. 


virtual IFlyOverHelpHandler& Supported On: 

setLongTextControl ( ITextControl* longText); PM 


Resource Library 

Use these members to query and set the resource library from which the information strings are 
loaded. 


resourceLibrary 

Returns a reference to the library being used. 


virtual IResourceLibrary& Supported On: 

resourceLibrary() const; PM 

setResourceLibrary 

Sets the resource library to be used. This can be specified as a module handle, a .dll 
file, or a library name. 

Q virtual IFlyOverHelpHandler& Supported On: 

setResourceLibrary( const char* resDLLName); PM 


§ virtual IFlyOverHelpHandler& Supported On: 

setResourceLibrary( const IModuleHandle& resMod); PM 

Special Information Strings 

Use these members to query and set the value of the information strings displayed in special 
circumstances. Special circumstances include when the information string is not found for the 
ITextControl. You can specify each special string as either an IString or the identifier for a 
string from the resource library. 

_ Returns the text to display when an information string is not found for the 
ITextControl. 
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virtual IString Supported On: 

defaul tText () const; PM 

setDefauItText 

Sets the text to display when an information string is not found for the ITextControl. 

[J virtual IFlyOverHelpHandler& Supported On: 

setDefaultText( unsigned long identifier); PM 

@ virtual IFlyOverHelpHandler& Supported On: 

setDefaultText( const IString& defaul tText); PM 
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String Table Offset 

Use these members to query and set a string table offset. This offset added to the window 
identifier for the window that the mouse is over is used to compute a value. The value is used to 
obtain a string from a string table. The default offset is 0. 

flyT extStringT ableOffset 

Returns the offset currently in use for the fly text control, 
virtual long 

flyTextStringTableOffset() const; 

longStringTableOffset 

Returns the offset currently in use for the long text control, 
virtual long 

1ongStringTableOffset() const; 

set FlyT extStri ngTableOffset 

Sets the offset to be used to calculate the information string identifier for the text 
displayed in the fly text control. 

virtual IFlyOverHelpHandler& Supported On: 

setFlyTextStringTableOffset( long newOffset = 0); PM 

setLongStringTableOffset 

Sets the offset to be used to calculate the information string identifier for the text 
displayed in the long text control. 

virtual IFlyOverHelpHandler& Supported On: 

setLongStringTableOffset( long newOffset = 0); PM 


Supported On: 

PM 


Supported On: 

PM 


Timer Delay 

Use these members query and set a timer delay. This timer delay specifies the time that the 
mouse must remain in the same location before help is displayed for the window under the 
mouse. 


_ Returns the minimum time, in milliseconds, the mouse must remain in the same 
position before help text is displayed. 
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virtual unsigned long 
delayTime() const; 


Supported On: 

PM 


initialDelayTime 

Returns the minimum time, in milliseconds, the mouse must remain in the same 
location for the first time fly over help is displayed for a window. 

virtual unsigned long Supported On: 

initialDelayTime() const; PM 

—Specifies the minimum time, in milliseconds, that the mouse must remain in the 
same position before help text is displayed. 


virtual IFlyOverHelpHandler& Supported On: 

setDelayTime( unsigned long milliseconds = 100); PM 

setlnitialDelayTime 

Sets the minimum time, in milliseconds, the mouse must remain in the same location 
for the first time fly over help is displayed for a window. 


virtual IFlyOverHelpHandler& 
setInitialDelayTime( unsigned long milliseconds = 100); 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Event Dispatching 

Event-dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process. 

dispatchHandlerEvent 

This function intercepts events that are necessary to determine which window the 
mouse is over. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM 


Inherited Protected Functions 



Inherited Protected Data 
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IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IFlyText 


_.None. 

—iflytext.hpp 


Member 

Page 

Member 

Page 

Constructor 

581 

setText 

581 

relati ve W indo wRect 

581 

'IFlyText 

581 

setRelativeWindowRect 

582 




Objects of this class display short help messages for the window that the mouse is 
currently over. 

The IFlytext control displays help messages in a bordered window that is sized just 
large enough to contain the help text. The text is displayed using one row and is not 
reflowed. The default font used to display the help messages is 8 point Helvetica. 

In addition to displaying the help message in a window with a border around it, 
IFlyText controls draw an arrow pointing outward from one of the four corners of the 
control. This arrow points to the window for which the help message is being 
displayed. 

The IFlyText control positions itself relative to one of the comers of the window that 
the mouse is over. The objective is to display the help message such that none of the 
text is drawn outside of the desktop, thereby clipping the text. This also determines 
which corner of the IFlyText control the arrow is drawn from. There are 
circumstances where it is impossible to display the help message without drawing off 
the desktop. The order the IFlyText control attempts to position itself relative to the 
window the mouse is over follows: 

• Lower right 
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• Lower left 

• Upper left 

• Upper right 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

_Use this function to construct objects of the IFlyText class from a window identifier 
and an owning window. 

IFlyText( unsigned long identifier, Supported On: 

IWindow* owner); PM 


"IFlyText 


virtual Supported On: 

"IFlyTextO; PM 

Text 

Use these members to set the text of the IFlyText control. 

..Sets the control window text. 


Q virtual IFlyText& Supported On: 

setText( const IResourceId& text); PM 


£ virtual IFlyText& 

setText( const char* text); 


Supported On: 

PM 


Window Positioning 

Use these members to get and set the position which the IFlyText control will position itself 
relative to. 


relativeWindowRect 

This function returns the rectangle of the control which the IFlyText control is 
positioned relative to. 
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virtual IRectangle Supported On: 

relativeWindowRect() const; PM 

setRelativeWindowRect 

This function set the rectangle of the window for which the IFlyText control will 
position itself relative to. This rectangle should be relative to the desktop window. 


virtual IFlyText& 

setRelativeWindowRect( const IRectangle& rect); 


Supported On: 

PM 


Inherited Public Functions 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 
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Note: Members of IWindow (Vol. II) are not shown. 


Inherited Public Data 


ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoIorld 

systemCommandld 

deleteld 

hiliteForegroundCoIorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFont 


IBase 

IVBase 

IFont 


_.None. 




—ifont.hpp 




Member 

Page 

Member 

Page 

Constructor 

586 

name 

593 

avgCharWidth 

589 

operator = 

587 

avgLowercase 

589 

pointSize 

593 

avgUppercase 

590 

pointSizeAt 

588 

beginUsingFont 

588 

setAllEmphasis 

595 

charWidth 

590 

setBold 

595 

endUsingFont 

588 

setCharHeight 

596 

extemalLeading 

590 

setCharSize 

596 

faceNameAt 

587 

setCharWidth 

596 

fattrs 

585 

setDirection 

594 

fontmetrics 

586 

setFontAngle 

596 

internalLeading 

590 

setFontShear 

597 

isBitmap 

593 

setltalic 

595 

isBitmapOnly 

588 

setName 

595 

isBold 

594 

setOutline 

595 

isFixed 

593 

setPointSize 

596 

isltalic 

594 

setStrikeout 

595 

isNonPropOnly 

588 

setUnderscore 

595 

isOutline 

594 

setWindowFont 

597 

isStrikeout 

594 

subscriptOffset 

592 

isUnderscore 

594 

subscriptSize 

592 

isVectorOnly 

588 

superscriptOffset 

592 

maxAscender 

591 

superscripts ize 

592 

maxCharHeight 

591 

textLines 

592 

maxDescender 

591 

textWidth 

593 

maxLowercaseAscender 

591 

useBitmapOnly 

589 

maxLowercaseDescender 

591 

useNonPropOnly 

589 

maxSize 

591 

useVectorOnly 

589 

maxUppercaseSize 

591 

"IFont 

587 

minTextWidth 

592 




Objects of the IFont class manage the use of fonts. Use these objects to select a font 
through the IFont functions. You can also use the font dialog to: 
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• Get font information 

• Set the font when drawing text 

IFont attempts to match the requested font. If it cannot find an exact match, IFont 
uses the nearest match. 

Note: An IFont object represents a particular font that is available on the system. It 
does not represent: 

• A font actually being used by a control 

• The currently selected font for a presentation space 

IWindow::setFont (Vol. II) changes the font used to draw text in a control. 

beginUsingFont (p. 588) causes all subsequent text drawn to the specified 
presentation space to be in the font represented by the IFont object. You can 
use beginUsingFont in conjunction with an IPaintHandler (Vol. II) object. 

IPM Some of the set and use functions (such as setCharHeight and useBitmapOnly) 

accept an optional parameter of type IPresSpaceHandle (Vol. II). If you are are using 
IFont to represent printer fonts, you should provide this parameter. If you do not 
specify a presentation space, IFont uses the presentation space of the desktop. 

[_j Some of the set and use functions, such as setCharHeight and useBitmapOnly, accept 

an optional parameter of type IPresSpaceHandle (Vol. II). Because the AIX version 
of IFont does not support printer fonts, there is no need to supply the optional 
IPresSpaceHandle parameter. 

The functions in this class that refer to vector fonts use scalable fonts in the X/Motif 
environment. 

ee If you are porting an OS/2 Presentation Manager program to Motif, be aware that the 
font names vary between these systems. The only fonts that you can be reasonably 
sure of finding on both Motif and Presentation Manager are Courier and Helvetica. 

On either system, if you try to construct an IFont object for a nonexistent font, you 
will get Courier as the default font. 


Public Functions 

Accessing Presentation Manager Structures Related to Font 

Use these members to access Presentation Manager structures. 

Returns a pointer to the font's OS/2 Presentation Manager FATTRS structure. 
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const struct _FATTRS* Supported On: 

fattrs() const; PM 

—Returns a pointer to the font's OS/2 Presentation Manager FONTMETRICS 
structure. 


const struct _FONTMETRICS* 
fontmetrics() const; 


Supported On: 

PM 


Constructors 

Use these members to construct, copy, assign and desttoy objects of this class. 


IFont 


[J I Font ( const IFont& fntCopy); Supported On: 

PM, Motif 

You can construct objects of this class from another IFont object. The parameter for 
this constructor is: 

fntCopy The font you want to copy. 

5 I Font ( const IWindow* window = 0); Supported On: 

PM, Motif 

You can construct objects of this class using a window's font. This constructs a font 
from the current font being used in the window. 

Note: In OS/2, if the IWindow* is a multiple-line edit field (MLE), Presentation 
Manager returns the desktop presentation space instead of the MLE 
presentation space. In doing so, a different font is displayed. 

The parameter for this consUuctor is: 

window The window to query for the font to use. 

If you do not specify a window, the system default font is used. In the AIX release, 
if you do not specify a window, the default font of the current display is used. 

0 IFont( const char* faceName, Supported On: 

unsigned long pointSize = 0, PM, Motif 

Boolean useFixedFont = false, 

Boolean useVectorFont = false, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( )); 
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You can construct objects of this class by specifying the name and size of the font 
desired, along with additional parameters. The parameters for this constructor are the 
following: 

faceName The face name of the font you want. 
pointSize The specific point size you want for the font. 
useFixedFont 

Specify whether you want the font fixed or proportional. The default is 
proportional. 

useVectorFont 

Specify whether you want a vector or bit-map font. The default is a 
bit-map font. 

presSpaceHandle 

The presentation space handle. 


0 I Font ( const IPresSpaceHandl e& presSpaceHandle); Supported On: 

PM. Motif 

You can construct objects of this class using a presentation space. This constructs a 
font corresponding to the font used in the specified presentation space. The 
parameter for this constructor is: 

presSpaceHandle 

The presentation space handle. 

.Assigns the value of one font object to another. 

IFont& Supported On: 

operator =( const IFont& rhs); PM. Motif 


~IFont 


virtual Supported On: 

"IFont(); PM, Motif 

Cursor-Related Functions 

Use these members with a cursor to retrieve font information. 

-..Queries a font face name for the current position of the specified cursor. 
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static IString Supported On: 

faceNameAt( const FaceNameCursor& faceNameCursor); PM 

—Queries the point size of a font for the current position of the specified cursor. 


static long 

pointSizeAt( const PointSizeCursor& pointSizeCursor); 


Supported On: 

PM 


Drawing Functions 

Use these members to draw text using a font. 


beginUsingFont 

Sets the presentation space to use the font. 


virtual IFont& 
beginUsingFont( 

const IPresSpaceHandle& presSpaceHandle); 


Supported On: 

PM. Motif 


Exceptions 

IAccessError The operating system is unable to create or set the font. 


endUsingFont 

Restores the presentation space to the default font. 


virtual IFont& 

endUsingFont( const IPresSpaceHandle& presSpaceHandle); 


Supported On: 

PM. Motif 


Font Types 

Use these members to query and set the types of fonts used by the IFont object. 
_.If the IFont object uses only bit-map fonts, true is returned. 


Boolean 

isBitmapOnly() const; 


Supported On: 

PM. Motif 


isNonPropOnly 

If the IFont object uses only non-proportional fonts, true is returned. 


Boolean 

isNonPropOnly() const; 

_If the IFont object uses only vector fonts, true is returned. 


Supported On: 

PM. Motif 
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Boolean 

isVectorOnly() const; 


useBitmapOnly 

Sets whether the IFont object uses only bit-map fonts. 


virtual IFont& 
useBitmapOnly( 

Boolean bitmapOnly = true, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( 


useNonPropOnly 

Sets whether the IFont object uses only non-proportional fonts. 


virtual IFont& 
useNonPropOnly( 

Boolean nonProportionalOnly = true, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( 


useVectorOnly 

Sets whether the IFont object uses only vector fonts. 


virtual IFont& 
useVectorOnly( 

Boolean vectorOnly = true, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( 


Geometry Accessors 

Use these members to query information about the size of the font. 


avgCharWidth 

Returns the average character's width. 


unsigned long 
avgCharWidth() const; 


avg Lowercase 

Returns the nominal height above the baseline for lowercase characters. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 

)); 


Supported On: 

PM, Motif 

)); 


Supported On: 

PM, Motif 

)); 


Supported On: 

PM, Motif 
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unsigned long 
avgLowercase() const; 


Supported On: 

PM, Motif 


avgUppercase 

Returns the height of the Em square. This corresponds to the point size. 

unsigned long Supported On: 

avgUppercaseQ const; PM, Motif 

- Returns the width of a specific single-byte character. 

c A character. You can only specify SBCS characters. 


unsigned long Supported On: 

charWidth( char c) const; PM. Motif 

IPM This member function is not DBCS-enabled. 

IMotiil This member function is not MBCS-enabled. 

externalLeading 

Returns the amount of white space that should appear between adjacent rows of text. 


unsigned long 
externalLeading() const; 


Supported On: 

PM, Motif 


internalLeading 

Returns the approximate position of the top of a row of characters. You can use this 
value to position the first line of a block of text by: 

1. Subtracting the internalLeading value from the value returned by maxAscender 
(P- 591). 

2. Positioning the baseline of the first line of text below the item (such as text or 
graphics) that is above the text. Use the value you obtained in step 1 to do so. 

Note: There is no guarantee that the positioned characters will not write over the 
item that is above them. Test to see if anything is over-written and allocate 
additional space, if necessary. 

unsigned long Supported On: 

internal LeadingO const; PM. Motif 
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maxAscender 

Returns the height of the largest ascender above the baseline. 

unsigned long 
maxAscender() const; 


maxCharHeight 

Returns the height portion of IFont::maxSize (p. 591). 

unsigned long 
maxCharHeight() const; 


maxDescender 

Returns the height of the largest descender below the baseline. 

unsigned long 
maxDescender() const; 

maxLowercaseAscender 

Returns the height of the largest lowercase ascender. 

unsigned long 

maxLowercaseAscender() const; 

maxLowercaseDescender 

Returns the height of the largest lowercase descender. 

unsigned long 

maxLowercaseDescender() const; 

Returns the maximum width and height. 

ISi ze 

maxSize() const; 

maxUppercaseSize 

Returns the maximum size for an uppercase character. 

ISi ze 

maxUppercaseSize() const; 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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minTextWidth 

Returns the width of the widest word. 

line Pointer to character string. You can only specify an SBCS string. 


unsigned long Supported On: 

minTextWidth( const char* line) const; PM. Motif 

IPM This member function is not DBCS-enabled. 

IMotiil This member function is not MBCS-enabled. 

subscriptOffset 

Returns the recommended size of the baseline X-Y offset for subscripts. 

ISize 

subscriptOffset() const; 


Supported On: 

PM. Motif 


subscriptSize 

Returns the recommended size for subscripts. 


ISize 

subscriptSize() const; 


Supported On: 

PM. Motif 


superscriptOffset 

Returns the recommended size of the baseline X-Y offset for superscripts. 


ISize 

superscriptOffset() const; 


Supported On: 

PM. Motif 


superscriptSize 

Returns the recommended size for superscripts. 

ISize Supported On: 

superscriptSize() const; PM. Motif 

Returns the number of lines required to fit the specified text using the specified 
maximum line width. 

text Pointer to character string. You can only specify an SBCS string. 

lineWidth The maximum line width. 


592 


Open Class Library Reference 



IFont 


unsigned long Supported On: 

textLines( const char* text, PM, Motif 

unsigned long lineWidth) const; 

IPM This member function is not DBCS-enabled. 

|Motif This member function is not MBCS-enabled. 

.Returns the width of the specified string. Warning: This member function is not 

DBCS-enabled. 

text Pointer to character string. You can only specify an SBCS string. 


unsigned long Supported On: 

textWidth( const char* text) const; PM, Motif 

IPM This member function is not DBCS-enabled. 

|Motif This member function is not MBCS-enabled. 

Getting Font Attributes 

Use these members to query the attributes of the current font. 

_If the IFont object uses a bit-map font, true is returned. If the IFont object uses a 
vector font, false is returned. 


Boolean Supported On: 

isBitmapO const; PM, Motif 

.If the IFont object uses a fixed-size (that is, non-proportional) font, true is returned. 


Boolean Supported On: 

isFixedQ const; PM, Motif 

Returns the face name of the font. 


IString Supported On: 

name() const; PM, Motif 

Returns the point size of the font. 


unsigned long 
pointSize() const; 


Supported On: 

PM, Motif 
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Getting Font Style 

Use these members to query the appearance of a font. 

If the IFont object uses a font that is bold, true is returned. 


Boolean Supported On: 

isBold() const; PM. Motif 

If the IFont object uses an italicized font, true is returned. 


Boolean Supported On: 

isItalicQ const; PM, Motif 

..If the IFont object uses a font that appears hollow, true is returned. 


Boolean Supported On: 

isOutline() const; PM, Motif Ignored 

_.If the IFont object uses a font with a line drawn through the characters, true is 
returned. 


Boolean Supported On: 

l'sStrikeoutO const; PM, Motif Ignored 

If the IFont object uses a font with a line drawn under the characters, true is 
returned. 


Boolean 

isUnderscore() const; 


Supported On: 

PM, Motif Ignored 


Setting Font Direction 

Use these members to set the direction that the font is drawn in. 

... Sets the direction to draw the font in. 

direction Use the enumeration Direction (p. 598) to specify the direction. 


IMotifl 


virtual IFont& Supported On: 

setDi recti on ( Direction direction); PM, Motif Ignored 

In the AIX release, the system locale information determines the font direction. 
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Setting Font Style 

Use these members to change the appearance of a font. 


setAIIEmphasis 

If you specify true, all of the styles are set on. If you specify false, all of the styles 
are set off. 

virtual IFont& 

setAl1Emphasis( Boolean turnOn = true); 

Changes to bold font. 

virtual IFont& 

setBold( Boolean bold = true); 

...Changes to italic font. 

virtual IFont& 

set Italic ( Boolean italics = true); 

- Causes the font to appear hollow. 

virtual IFont& 

setOutline( Boolean outline = true); 

- Draws a line through the characters. 

virtual IFont& 

setStrikeout( Boolean strikeout = true); 


setUnderscore 

Draws a line under the characters. 


virtual IFont& 

setl)nderscore( Boolean underscore = true); 

Setting General Font Attributes 

Use these members to set the attributes of any font being managed by the IFont class. 
-Sets the font's face name. 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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virtual IFont& Supported On: 

set Name ( PM, Motif 

const char* name, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( )); 

—Sets the font's point size. 


virtual IFont& 
setPointSize( 

unsigned long size, 

const IPresSpaceHandle& presSpaceFlandle = IPresSpaceHandle 


Supported On: 

PM, Motif 


)); 


Setting Vector Font Attributes 

Use these members to set the attributes of vector fonts. These members have no effect when 
applied to a bitmap font. 


setCharHeight 

Sets the height of the characters of a vector font. This function has no effect when 
applied to a bit-map font. 


virtual IFont& Supported On: 

setCharHeight( PM, Motif Ignored 

unsigned long height, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( )); 

—Sets the size of the characters of a vector font. This function has no effect when 
applied to a bit-map font. 

virtual IFont& Supported On: 

setCharSize( PM, Motif Ignored 

const ISize& size, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( )); 


setCharWidth 

Sets the width of the characters of a vector font. This function has no effect when 
applied to a bit-map font. 


virtual IFont& Supported On: 

setCharWi dth ( PM, Motif Ignored 

unsigned long width, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( )); 

— Sets the angle to draw the vector font with. This function has no effect when 
applied to a bit-map font. 
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virtual IFont& 
setFontAngl e( 

const IPoint& point, 

const IPresSpaceHandle& presSpaceHandle 


Supported On: 

PM, Motif Ignored 


IPresSpaceHandle ( )); 


setFontShear 

Sets the amount of shear to apply to the vector font. This function has no effect 
when applied to a bit-map font. 


virtual IFont& Supported On: 

setFontShear( PM, Motif Ignored 

const IPoint& point, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( )); 


Setting Window Font 

Use these members to apply the current font to an I Window 


setWindowFont 

Sets the font for the specified IWindow (Vol. II) to the current font. If the font is 
successfully changed, true is returned. 


virtual Boolean 

setWindowFont( IWindow* window) const; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system is unable to set the font for the window. 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


© IBM Corp. 1992, 1995 


IFont 597 






IFont 


Inherited Protected Data 



Nested Classes 

IFont contains the following nested classes: 

IFont: :PointSizeCursor (see page 602) 

IFont::FaceNameCursor (see page 599) 

Direction { 

defaultDir, leftToRight, 

rightToLeft, bottomToTop, 

topBottom = topToBottom, rightLeft = rightToLeft, 

}; 

Use these enumerators to specify the direction in which a font is drawn. You can use 
these enumerators as input to setDirection (p. 594). 

defaultDir 

Draws the font in the default direction. 

leftRight 

Draws the font from left to right. 

topBottom 

Draws the font from top to bottom. 

rightLeft 

Draws the font from right to left. 

bottomTop 

Draws the font from bottom to top. 

Note: The following enumerators are obsolete, use their replacements instead: 
Obsolete Replacement 

bottomTop bottomToTop 

leftRight leftToRight 

rightLeft rightToLeft 

topBottom topToBottom 


topToBottom, 

leftRight = leftToRight, 
bottomTop = bottomToTop 
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IFont::FaceNameCursor 


IBase 

IVBase 

IFont: :FaceNameCursor 


_.None. 


_Jfont.hpp 


Member 

Page 

Member 

Page 

Constructor 

599 

setToLast 

600 

FaceN ameCursor 

599 

setToNext 

600 

invalidate 

600 

setToPrevious 

600 

is Valid 

600 

“FaceNameCursor 

600 

setToFirst 

600 




Objects of the IFont: :FaceNameCursor nested class iterate over the public and private 
fonts available for a presentation space. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


FaceNameCursor 

You can construct objects of this class using a FontType enumerator and a 
presentation space handle. Both parameters are optional. The FontType enumerator 
specifies which type you want to cursor through. If you do not specify a presentation 
space, the desktop presentation space is used. 

fontType Type of font to cursor through. 

presSpaceHandle 

(Optional) Presentation space handle used to query the available fonts. 
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FaceNameCursor( 

FontType fontType = both, 

const IPresSpaceHandle& presSpaceHandle = IPresSpaceHandle ( 


FaceNameCursor 


virtual 

'FaceNameCursor(); 


Overrides 

Use these members to iterate through the available font face names. 
_Marks the cursor as not valid. 


virtual void 
invalidate(); 

Returns true if the cursor is valid. 


virtual Boolean 
isValid() const; 

.Advances the cursor position to the first face name. 


virtual Boolean 
setToFirst(); 

...Advances the cursor position to the last face name. 


virtual Boolean 
setToLast(); 

...Advances the cursor position to the next face name. 


virtual Boolean 
setToNext(); 


setToPrevious 

Advances the cursor position to the previous face name. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM 

)); 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



FontType { 
bitmap, 
vector, 
both 
}; 


Use this enumeration to specify which types of fonts (bit-map, vector, or both) you 
want to iterate through. 
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IFont::PointSizeCursor 


IBase 

IVBase 

IFont:: PointSizeCursor 


_.None. 


—ifont.hpp 


Member 

Page 

Member 

Page 

Constructor 

602 

setToLast 

603 

invalidate 

603 

setToNext 

603 

is Valid 

603 

setToPrevious 

603 

PointSizeCursor 

602 

'PointSizeCursor 

603 

setToFirst 

603 




Objects of the IFont::PointSizeCursor nested class iterate over the point sizes 
available for a font. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


PointSizeCursor 

You can construct objects of this class from the font face name and a presentation 
space handle. The presentation space handle is optional. If you do not specify it, the 
desktop presentation space is used. 

facename Font face name. 

presSpaceHandle 

(Optional) Presentation space handle used to query the point sizes. 
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PointSizeCursor( 

const char* facename, 
const IPresSpaceHandle& presSpaceHandle = 
IPresSpaceHandle ( )); 


PointSizeCursor 

virtual 

'PointSizeCursor(); 


Overrides 

Use these members to iterate through the available point sizes for a given font. 
_Marks the cursor as not valid. 


virtual void 
inval idate(); 

Returns true if the cursor is valid. 


virtual Boolean 
isValid() const; 

_. Advances the cursor position to the first point size. 


virtual Boolean 
setToFirst(); 

...Advances the cursor position to the last point size. 


virtual Boolean 
setToLast(); 

- Advances the cursor position to the next point size. 


virtual Boolean 
setToNext(); 


setToPrevious 

Advances the cursor position to the previous point size. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFontDialog 


IBase 
IVBase 
INotifier 
IWindow 
IFrame W indo w 
IFontDialog 


_.None. 

__ifontdlg.hpp 


Member 

Page 

Member 

Page 

Constructor 

606 

isModeless 

609 

apply Button 

612 

modeless 

613 

bitmapOnly 

613 

nominalPointSize 

609 

buttonPressedld 

609 

noStyle 

613 

cancel 

612 

noSynthesize 

613 

classDefaultStyle 

613 

ok 

612 

con vertT oGUIS ty le 

610 

pointSize 

609 

defaultStyle 

610 

pressedOK 

610 

emHeight 

608 

proportionalOnly 

614 

extemalLeading 

608 

resetButton 

614 

fixed WidthOnly 

613 

return Value 

610 

fontFamily 

608 

setDefaultStyle 

610 

fontWeight 

608 

vectorOnly 

614 

fontWidth 

609 

xHeight 

609 

helpButton 

613 

“IFontDialog 

608 


Objects of the IFontDialog class display a font dialog for the user to choose a font. 
Once the user chooses a font, you can use accessor functions to retrieve information 
about the chosen font. 

The easiest way to use this class is to specify an IFont (p. 584) object on the 
IFontDialog::Settings constructor (p. 616). This causes the following to happen: 

• The specified IFont is used as the initially displayed font choice in the dialog. 

• If the user ends the dialog by selecting the OK push button, the specified IFont 
object is automatically changed to the font the user selected. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class but you cannot copy them. 

_Use these functions to construct IFontDialog objects. 

IPM In OS/2 Presentation Manager, you can have modal windows that do not use the 
desktop as their parent. However, Presentation Manager can change the owner 
window of your dialog to something other than what you specified to prevent your 
application from being hung. See the Presentation Manager Programming Reference 
Volume 2 for more information under WinLoadDlg. 

The easiest way to ensure that your dialog is modal is to use the desktop as the 
parent and an application window as the owner. Presentation Manager only disables 
the owner window and its child windows (the child windows of the child windows, 
and so forth) while a modal dialog is displayed. If you specify 0 for parent, the 
desktop automatically becomes the parent of the dialog. 

| IFontDialog( IWindow* parent, 

IWindow* owner, 

IHandler* handler, 

const Style& style = defaaltStyle ( ), 
const Settings& settings = Settings ( 0 )); 

You can construct an object of this class by using this constructor which accepts a 
parent, owner, handler, style and settings as parameters. 

In order to add a IFontDialogHandler (p. 621) to a modal IFontDialog, you must 
specify the handler on the constructor. Once you create a modal IFontDialog, the 
dialog does not return control to the application until the user closes the dialog. At 
that time, it is too late to add a handler. 

The parameters for this constructor are the following: 

parent The parent of the dialog box. If you specify 0, the desktop becomes the 
parent of the dialog. 

owner The owner window. 

handler A pointer to an IHandler (Vol. II) object. 

style (Optional) Use the styles provided by IFontDialog (p. 612) to specify the 

style. The default creates a modal dialog. To construct a modeless 
dialog, specify the modeless style. 


Supported On: 

PM, Motif 


606 Open Class Library Reference 



IFontDialog 


settings (Optional) Use the settings provided by IFontDialog::Settings (p. 616) to 
specify the setting. 

g I FontDialog( IWindow* parent. Supported On: 

IWindow* owner, PM. Motif 

const Style& style = defaultStyle ( )); 

You can construct an object of this class by using this constructor which accepts a 

parent, owner, and style as parameters. 

The parameters for this constructor are the following: 

parent The parent of the dialog box. If you specify 0, the desktop becomes the 
parent of the dialog. 

owner The owner window. 

style (Optional) Use the styles provided by IFontDialog (p. 612) to specify the 

style. The default creates a modal dialog. To construct a modeless 
dialog, specify the modeless style. 

g IFontDialog( IWindow* parent, 

IWindow* owner, 
const Settings& settings, 
const Style& style = defaultStyle ( )); 

You can construct an object of this class by using this constructor which accepts a 

parent, owner, settings and style as parameters. 

The parameters for this constructor are the following: 

parent The parent of the dialog box. If you specify 0, the desktop becomes the 
parent of the dialog. 

owner The owner window. 

settings Use the settings provided by IFontDialog::Settings (p. 616) to specify the 
setting. 

style (Optional) Use the styles provided by IFontDialog (p. 612) to specify the 

style. The default creates a modal dialog. To construct a modeless 
dialog, specify the modeless style. 

0 I FontDi al og ( IWindow* parent. Supported On: 

IWindow* owner, PM. Motif 

const Style& style, 

const Settings& settings); 


Supported On: 

PM, Motif 
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You can construct an object of this class by using this constructor which accepts a 
parent, owner, style and settings as parameters. 

The parameters for this constructor are the following: 

parent The parent of the dialog box. If you specify 0, the desktop becomes the 
parent of the dialog. 

owner The owner window. 

style Use the styles provided by IFontDialog (p. 612) to specify the style. The 

default creates a modal dialog. To construct a modeless dialog, specify 
the modeless style. 

settings Use the settings provided by IFontDialog::Settings (p. 616) to specify the 
setting. 

"IFontDialog 

virtual 

'IFontDialogO; 

Getting Information about the Chosen Font 

Use these members to get information about the font that was selected in the font dialog. 

_ Returns the height of the Em square for the font. 

unsigned long 
emHeight() const; 

externalLeading 

Returns the amount of white space between lines of text. 

unsigned long 
externalLeading() const; 

_ Returns the font's family name. 

IString Supported On: 

fontFamily() const; PM, Motif 

- Returns the weight class (boldness) of the font. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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unsigned long 
fontWeight() const; 

[ ~ This function always returns 0. 

.Returns the width class of the font. 


unsigned long 
fontWidth() const; 

| Motif This function always returns 0. 

nominalPointSize 

For a bit-map font, the height of the font is returned. For a 
size for the font is returned. 


unsigned long 
nominalPointSize() const; 

j_| For scalable fonts, this function returns 0. 


Returns the font's point size. 


unsigned long 
pointSize() const; 

Returns the height above the baseline for lowercase letters. 


unsigned long 
xHeight() const; 


Getting Information about the Dialog 

Use these members to get information about the dialog. 


buttonPressedld 

Returns the ID of the push button used to end the dialog. 


unsigned long 
buttonPressedId() const; 

_If the font dialog is modeless, true is returned. 


Boolean 

isModeless() const; 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM. Motif Ignored 


vector font, the optimal 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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_If the user ended the dialog by selecting the OK push button, true is returned. 


Bool ean Supported On: 

pressedOKQ const; PM, Motif 

_If an error occurs, the return code is returned. 


long 

returnValue() const; 


Supported On: 

PM, Motif 


Styles 

The style members provide a set of valid font dialog styles for IFontDialog::setDefaultStyle and 
the constructors of the IFontDialog (p. 605) class. 

convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

—Returns the default style. The default style is classDefaultStyle (p. 613) unless you 
have changed it using setDefaultStyle (p. 610). 


static Style 
defaultStyle(); 


Supported On: 

PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent font dialogs. 

style Use the styles provided by IFontDialog (p. 612) to specify the default 

style. 


static void 

setDefaultStyle( const Style& newDefault); 


Supported On: 

PM, Motif 
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Inherited Public Functions 


IFrameWindow 

addExtension 

isFlashing 

setBorderWidth 

addToWindowList 

isMaximized 

setClient 

backgroundColor 

isMinimized 

setDefaultOrdering 

beginFlashing 

isModal 

setDefaultStyle 

borderHeight 

maximize 

setDestroyOnClose 

borderS ize 

maximizeRect 

setExtensionSize 

borderWidth 

minimize 

setlcon 

client 

minimizeRect 

setLay outDi storted 

clientHandle 

mousePointer 

setMousePointer 

clientRectFor 

moveS izeToClient 

setRestoreRect 

close 

nextShellReet 

setResult 

convertToGUIStyle 

notifyOwner 

setToolBarList 

defaultOrdering 

removeExtension 

shareParentDBCSStatus 

defaultStyle 

removeFromWindowList 

show 

disabledBackgroundColor 

resetBackgroundColor 

showModally 

dismiss 

resetDisabledBackgroundColor 

start 

enableNotification 

restore 

toolBarList 

endFlashing 

restoreRect 

topHandle 

frameRectFor 

result 

update 

handleFor 

setBorderHeight 

useExtensionMinimumSize 

icon 

setBorderSize 

usesDialogBackground 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 
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Inherited Protected Functions 


IF rameWindow 

addDefaultHandler 

findExtensions 

registerFrameClass 

attachClient 

initialize 

removeDefaultHandler 

create 

isFrameWindow 

setExtensions 

extensions 

isRelatedHandle 

tryToLoadDialog 

findExtension 

registerCallbacks 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 

Getting Information about the Dialog 

Use these members to get information about the dialog. 

.Push button ID value returned when the dialog is dismissed by pressing the Cancel 
button. 

static const unsigned long Supported On: 

cancel; PM. Motif 

Push button ID value returned when the dialog is dismissed by pressing the OK 
button. 


static const unsigned long 
ok; 


Supported On: 

PM. Motif 


Styles 

The style members provide a set of valid font dialog styles for IFontDialog::setDefaultStyle and 
the constructors of the IFontDialog (p. 605) class. 

_.Adds an Apply push button to the dialog. This is useful in a modeless dialog. 

static const Style Supported On: 

applyButton; PM. Motif 
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—Specifies the dialog present bit-map fonts only. 


static const Style 
bitmapOnly; 


Supported On: 

PM, Motif 


classDefaultStyle 

Specifies the original default style for this class, which is a static variable set to 0 
indicating no style flags are set. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM, Motif 


fixedWidthOnly 

Specifies the dialog present fixed-width (monospace) fonts only. 


static const Style Supported On: 

fixedWidthOnly; PM, Motif 

—Adds a Help push button to the dialog. This push button sends a help message to 
the owner of the dialog. 


static const Style Supported On: 

helpButton; PM, Motif 

^Specifies the dialog is modeless. The constructor for a modeless dialog returns 
immediately. To determine the font chosen by the user, create an IFontDialogHandler 
and use IFontDialog::modelessResults (p. 623). 


static const Style Supported On: 

modeless; PM, Motif 

Disables all of the valid styles. Use this style only when you are not using any 
other styles. 


static const Style 
noStyle; 


Supported On: 

PM, Motif 


noSynthesize 

Specifies the dialog does not manipulate bit-map fonts to synthesize features, such as 
italics or bold. 
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static const Style 
noSynthesize; 


Supported On: 

PM, Motif 


proportionalOnly 

Specifies the dialog present proportionally-spaced fonts only. 


static const Style Supported On: 

proportionalOnly; PM, Motif 

—Adds a Reset push button to the dialog. When this push button is selected, the 
values for the dialog are restored to their initial values. 


static const Style Supported On: 

resetButton; PM, Motif 

—Specifies the dialog present vector fonts only. 


static const Style 
vectorOnly; 


Supported On: 

PM, Motif 


Inherited Public Data 


IF rameWindow 

activateld 

eloseld 

deactivateld 


IWindow 

activeColorld 

disabledF oregroundColorld 

hiliteF oregroundColorld 

backgroundColorld 

enableld 

inactiveColorld 

borderColorld 

focusld 

positionld 

commandld 

fontld 

shadowColorld 

deleteld 

foregroundColorld 

sizeld 

disabledBackgroundColorld 

hiliteBackgroundCoIorld 

systemCommandld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Nested Classes 

IFontDialog contains the following nested classes: 

IFontDialog::Settings (see page 616) 
IFontDialog::Style (see page 620) 


© IBM Corp. 1992, 1995 


IFontDialog 615 



IF ontDialog:: Settings 



IFontDialog::Settings 


IBase 

IFontDialog:: Settings 


_.None. 


_Jfonttllg.hpp 


Member 

Page 

Member 

Page 

Constructor 

617 

setPreviewText 

617 

setDialogTemplate 

617 

setPrinterPS 

619 

setDisplayPS 

618 

setSizeList 

618 

setFamily 

618 

Settings 

617 

setFont 

618 

setTitle 

617 

setPointSize 

618 

'Settings 

617 

setPosition 

617 




Objects of the IFontDialog::Settings class contain input for an IFontDialog (p. 605) 
object. The font dialog displays with the items you specify in the Settings object. If 
you do not specify a Settings object on the IFontDialog constructor, a default Settings 
object is constructed for you. This default object provides a font dialog with no other 
settings in effect. You can pass the following items within an IFontDialog::Settings 
object to an IFontDialog: 

• The dialog title 

• The push button arrangement on the dialog 

• The characteristics of the fonts to present, such as family or point size 

IPM You can also pass the following items within a Settings object: 

• The presentation space from which the dialog generates the font list 

• A dialog template to use in place of the system default dialog 


Public Functions 
Constructors 

You can construct and destruct object of this class. There is one constructor, the default, which 
accepts an optional IFont object. If you specify an IFont object, it is used as the initially 
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selected font in the dialog. If the user selects the OK push button, the specified font is changed 
to the font selected by the user. 


Settings 

Settings( IFont* font = 0); Supported On: 

PM, Motif 

You can construct an object of this class by using this constructor, which accepts an 
optional IFont object. If specified, this IFont object is used to specify the initial font 
to display in the dialog. 

"Settings 


"Settings(); Supported On: 

PM, Motif 

Dialog Customization 

Use these members to customize the font dialog presented to the user. This includes the dialog's 
title, font preview text, dialog position and the dialog template to use. 

setDialogTemplate 

Sets a dialog template resource to use in place of the OS/2-supplied default font 
dialog. 

Settings& Supported On: 

setDialogTemplate( const IResourceId& templateld); PM 

_.Sets the initial placement of the dialog. 


Settings& 

setPosition( const IPoint& position); 


Supported On: 

PM, Motif 


setPreviewText 

Sets the text to display in the font sample box. 


Settings& Supported On: 

setPreviewText ( const char* previewText); PM, Motif 

..Sets the font dialog's title. 


© IBM Corp. 1992, 1995 


IFontDialog::Settings 617 



IF ontDialog:: Settings 


[] Settings& 

setTitle( const IResourceId& text); 


Supported On: 

PM, Motif 


| Settings& 

setTitle( const char* title); 


Supported On: 

PM, Motif 


Setting Information about the Initial Font 

Use these members to set information about the initial font that is displayed in the font dialog. 
_Sets the font family name for the initial set of fonts displayed in the font dialog. 


Settings& Supported On: 

setFamily( const char* fontFamily); PM, Motif 

...Sets the font to be displayed as the initial selection in the dialog. 


Settings& Supported On: 

setFont( IFont* font); PM 

.....Sets the point size for the initial set of fonts displayed in the font dialog. 


Settings& Supported On: 

setPointSize( unsigned long pointSize); PM, Motif 

IMotifl If you specify a point size of 0, X-scalable fonts are displayed. 

....Sets the list of point size choices. 


Settings& Supported On: 

setSizeList( const char* sizeList); PM, Motif 

IPM This only affects dialogs for vector fonts in an OS/2 system. A dialog for an OS/2 
bit-map font has the size list automatically set to the available sizes for the bit-map 
font. 

IMotifl This function has no effect in Motif. 

Setting the Presentation Space 

Use these members to set the presentation space that is used to determine which fonts are 
available. 


_Sets the display's presentation space. The dialog uses this presentation space to 
determine which fonts are available. 
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Settings& Supported On: 

setDi spl ay PS ( PM, Motif Ignored 

const IPresSpaceHandle& presSpaceHandl e); 

_Sets the printer's presentation space. The dialog uses this presentation space to 
determine which fonts are available for the printer. 


Settings& 
setPrinterPS( 

const IPresSpaceHandle& presSpaceHandle); 


Supported On: 

PM. Motif Ignored 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFontDialog::Style 


IBase 

IBitFlag 

IFontDialog::Style 


_.None. 

... ifontdlg.hpp 

The nested class IFontDialog::Style provides a set of valid styles for the IFontDialog 
(p. 605) class. 

IMotifl In Motif, the style vectorOnly specifies the dialog present scalable fonts only. AIX 
does not support the noSynthesize style. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

set Value 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFontDialogHandler 


IBase 

IVBase 

IHandler 

IFontDialogHandler 


_.None. 


_ ifonthdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

622 

modelessResults 

623 

dispatchHandlerEvent 

623 

“IFontDialogHandler 

622 


Objects of the IFontDialogHandler class handle the various messages that affect the 
font dialog. 

Create a handler derived from IFontDialogHandler and attach it to a font dialog. You 
can do this by calling IHandler::handleEventsFor (Vol. II) to pass the appropriate font 
dialog to the font dialog handler. 

Note: To add a handler to a modal font dialog, you must specify a pointer to the 
handler on the IFontDialog (p. 605) constructor. 

When the font dialog handler receives a font dialog event, it creates an IFontDialog 
object and routes that object to the IFontDialogHandler::modelessResults (p. 623) 
virtual function. Override this virtual function to supply your own specialized 
processing of a font dialog event. 

The return value from the virtual function specifies whether the font dialog event is 
passed on for additional processing, as follows: 

true The font dialog event requires no additional processing. Do not pass it to 
another handler. 

false Pass the font dialog event to the next handler for additional processing, as 
follows: 

• If there is another handler for the font dialog, pass the font dialog event 
to the next handler. 
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• If this is the last handler for the font dialog, call 

IWindow::defaultProcedure (Vol. II) to process the font dialog event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IFontDialogHandler 

You can only construct objects of this class using the default constructor, which does 
not accept any parameters. 

IFontDialogHandlerQ; Supported On: 

PM, Motif 


"IFontDialogHandler 


virtual 

''IFontDialogHandlerO; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Dispatch Events 

These members determine if the event is one of the font dialog events. If it is, it calls the 
appropriate function. 

dispatchHandlerEvent 

If a font dialog event is received, the appropriate virtual function is called. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


Font Dialog Dismissal 

These members are called when a font dialog is dismissed. You should override these members 
to determine how the font dialog was dismissed. 


modelessResults 

Called when a modeless dialog is ended. This function is called even if the dialog is 
cancelled. This is done so that you can destroy the IFontDialog (p. 605) if needed. 
Use IFontDialog::pressedOK (p. 610) to determine whether the user ended the dialog 
by pressing the Ok push button. 

If you need to destroy the IFontDialog object, do not delete the IFontDialog* pointer 
from within IFontDialog::modelessResults. Instead, call: 

endingDialog->setAutoDeleteObj ect(). 


virtual Boolean 

modelessResults( IFontDialog* endingDialog) = 0; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IG3PointArc 


IBase 

IVBase 

IGraphic 

IG3PointArc 


_.None. 


—igarc.hpp 

Member 

Page 

Constructor 

626 

drawOn 

628 

endingPoint 

627 

intermediatePoint 

627 

operator != 

625 

operator = 

626 


Member 

Page 

operator == 

626 

setEndingPoint 

627 

setlntermediatePoint 

627 

setStartingPoint 

627 

startingPoint 

627 

~IG3PointArc 

627 


The IG3PointArc class is a graphic object class that allows you to create 
two-dimensional arcs by specifying three points the arc passes through. Unless you 
apply a transform to objects of this class, the three points will specify an arc of a 
circle. 

When you draw an IG3PointArc, the following graphic bundle attributes affect its 
appearance: 

• Pen color 

• Mix mode 

• Pen width 

• Pen type 

• Pen ending style 


Public Functions 
Comparisons 

Use these members to compare two IG3PointArc objects. 

_ Returns true if the arcs are not identical (includes the graphic bundle attributes and 
the transform matrix). 
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I Base:: Boolean Supported On: 

operator ! = ( const IG3PointArc& arc) const; PM 

..Returns true if the arcs are identical (includes the graphic bundle attributes and the 
transform matrix). 


IBase::Boolean 

operator ==( const IG3PointArc& arc) const; 


Supported On: 

PM 


Constructors 

You can construct, destruct, copy, and assign objects of the this class. 

IG3PointArc 

[J IG3PointArc( const IPoint& starting, Supported On: 

const IPoint& intermediate, PM 

const IPoint& ending); 

Use this function to construct a IG3PointArc object from three points. The first point 
defines the starting location of the arc, the second point defines an intermediate point 
along the arc, and the last point defines the end point of the arc. 

starting First point of the arc. 

intermediate 

Point on the arc between the starting and ending points. 
ending End point of the arc. 

2 IG3PointArc( const IG3PointArc& arc); Supported On: 

PM 

Use this function to construct a IG3PointArc object from another IG3PointArc object. 
arc Reference to another IG3PointArc object. 

_ Use this function to assign a IG3PointArc object to another IG3PointArc object. 

IG3PointArc& Supported On: 

operator =( const IG3PointArc& arc); PM 
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~IG3PointArc 


virtual 

"IG3PointArc(); 


Data Access 

Use these members to set and query the points that the arc passes through. 
_Returns the ending point of the arc. 

virtual IPoint 
endingPoint() const; 

intermediatePoint 

Returns the intermediate point of the arc. 


virtual IPoint 

intermediatePoint() const; 


setEndingPoint 

Sets the ending point of the arc. 

virtual IG3PointArc& 

setEndingPoint( const IPoint& point); 

setlntermediatePoint 

Sets the intermediate point of the arc. 


virtual IG3PointArc& 

setIntermediatePoint( const IPoint& point); 


setStartingPoint 

Sets the starting point of the arc. 


virtual IG3PointArc& 

setStartingPoint( const IPoint& point); 

_Returns the starting point of the arc. 


virtual IPoint 

startingPoint() const; 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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Drawing 

Use these members to render the graphic object. 

Draws the arc on the device associated with the graphic context. 


virtual IG3PointArc& 

drawOn( IGraphicContext& graphicContext); 


Supported On: 

PM 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IGArc 


IBase 

IVBase 

IGraphic 

IGArc 


_.None. 


—igarc.hpp 

Member 

Page 

Constructor 

630 

direction 

631 

drawOn 

631 

enclosingRect 

631 

operator != 

630 

operator = 

630 

operator == 

630 


Member 

Page 

setDirection 

631 

setEnclosingRect 

632 

setS tart Angle 

632 

setSweepAngle 

632 

startAngle 

632 

sweepAngle 

632 

"IGArc 

631 


The IGArc class is a graphic object class that allows you to create two-dimensional 
arcs by specifying a bounding rectangle, a start angle and a sweep angle. The 
rectangle you specify in the constructor is the enclosing rectangle of an ellipse. The 
start angle and sweep angles specify an arc section of this ellipse. 

When you draw an IGArc, the following graphic bundle attributes affect its 
appearance: 

• Pen color 

• Mix mode 

• Pen width 

• Pen type 

• Pen ending style 


Public Functions 
Comparisons 

Use these members to compare two IGArc objects. 
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..Returns true if the arcs are not identical (includes the graphic bundle attributes and 
the transform matrix). 

I Base:: Boolean Supported On: 

operator ! = ( const IGArc& arc) const; PM 

..Returns true if the arcs are identical (includes the graphic bundle attributes and the 
transform matrix). 

I Base:: Boolean Supported On: 

operator ==( const IGArc& arc) const; PM 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 


IGArc 


[J IGArc( const IRectangle& rectangle, Supported On: 

double startAngle, PM 

double sweepAngle); 

Use this function to construct a IGArc object from a IRectangle object and a start and 
sweep angle. The rectangle specifies an enclosing rectangle of an ellipse. The start 
and sweep angles define an arc section of the ellipse. 

rectangle Defines the enclosing rectangle of an ellipse. 

startAngle Defines the starting angle of an arc section of the ellipse defined by the 
IRectangle object. 

sweepAngle 

Defines the sweep angle of an arc section of the ellipse defined by the 
IRectangle object. 

2 IGArc( const IGArc& arc); Supported On: 

PM 


Use this function to construct a IGArc object from another IGArc object. 
arc A reference to a IGArc object. 

. Use this function to assign a IGArc object to another IGArc object. 
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IGArc& Supported On: 

operator =( const IGArc& arc); PM 


"IGArc 


virtual Supported On: 

"IGArcO; PM 


Direction 

Use these members to set and query the direction that the arc is drawn in. The direction controls 
whether the sweep angle of the arc is drawn in a clockwise or counterclockwise direction. 

Returns the direction the arc is drawn. The default direction is counterclockwise. 


virtual Direction Supported On: 

direction() const; PM 

—Sets the direction the arc is drawn. 


virtual IGArc& 

setDirection( Direction direction = counterclockwise); 


Supported On: 

PM 


Drawing 

Use these members to render the graphic object. 

Draws the arc on the device associated with the graphic context. 


virtual IGArc& 

drawOn( IGraphicContext& graphicContext); 


Supported On: 

PM 


Enclosing Rectangle 

Use these members to set and query the enclosing rectangle of an ellipse. The arc is a section of 
this ellipse as specified by the start and sweep angles. The rectangle specifies an enclosing 
rectangle of an ellipse. The start and sweep angles define an arc section of the ellipse. 


enclosingRect 

Returns the enclosing rectangle of the ellipse which the arc is a section of. 


virtual IRectangle 
enclosingRect() const; 


Supported On: 

PM 
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setEnclosingRect 

Sets the enclosing rectangle of an ellipse. The arc is a section of this ellipse. 

virtual IGArc& Supported On: 

setEnclosingRect( const IRectangle& rectangle); PM 


Start and Sweep Angles 

Use these members to set and query the start and sweep angles of the arc. The start angle 
specifies the angle where the arc begins. The sweep angle continues from the start angle, 
defining an arc section of the ellipse. 


setStart Angle 

Sets the start angle, in degrees, of the arc (0<= angle <= 360). 


virtual IGArc& 

setStartAngle( double startAngle); 


Supported On: 

PM 


setSweep Angle 

Sets the sweep angle, in degrees, of the arc (0 <= angle <= 360). 


virtual IGArc& Supported On: 

setSweepAngle( double sweepAngle); PM 

.Returns the start angle in degrees. 


virtual double Supported On: 

startAngle() const; PM 

_Retums the sweep angle in degrees. 


virtual double 
sweepAngle() const; 


Supported On: 

PM 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 
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IGraphic 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Direction { 
clockwise, 
counterclockwise 
}; 
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IGBitmap 


IBase 

IVBase 

IGraphic 

IGBitmap 


_.None. 

—igbitmap.hpp 


Member 

Page 

Member 

Page 

Constructor 

637 

reflectHorizontally 

640 

asPointerHandle 

635 

reflect Vertically 

640 

black 

645 

resetTransparentColor 

637 

copy 

635 

rotateByl80 

641 

destlnvert 

645 

rotateBy270 

641 

drawOn 

639 

rotateBy90 

641 

halftone 

645 

setTransparentColor 

637 

handle 

635 

setViewOption 

642 

hasTransparentColor 

636 

size 

636 

imageFormat 

643 

sizeTo 

636 

invert 

645 

sourceAnd 

646 

loadBitmap 

644 

sourceErase 

647 

mergeCopy 

645 

sourcelnvert 

647 

mergePaint 

646 

sourcePaint 

647 

moveTo 

636 

transparentColor 

637 

normal 

646 

transposeXForY 

641 

notSourceErase 

646 

tryToLoadBitmap 

644 

patternCopy 

646 

viewOption 

642 

patternlnvert 

646 

white 

647 

patternPaint 

646 

writeToFile 

643 

position 

636 

'IGBitmap 

639 


The IGBitmap class is used to create, modify, and draw bitmaps. IGBitmap objects 
can be created from existing bitmap handles, from bitmap resources, from a 
rectangular area of a graphic context, or directly from an image file. 

Once a bitmap has been created, you can save the bitmap in any of the supported 
image file formats. 
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If the bitmap is a color bitmap, none of the graphic bundle attributes affects the 
appearance of the bitmap. If the bitmap is a monochrome (1 bit-per-plane) bitmap, 
then the following graphic bundle attributes affect its appearance. 

• Pen color 

• Background color 

• Mix mode 

• Background mix mode 


Public Functions 
Accessors 

Use the members to return the bitmap as an IBitmapHandle object or as an IPointerHandle 
object. 

asPointerHandle 

Converts the bitmap to a pointer and returns a IPointerHandle object. It is your 
responsibility to delete the pointer. 

Note: The bitmap transparent color is not used when creating the pointer. 

virtual IPointerHandle Supported On: 

asPointerHandle() const; PM 

Returns the handle of the bitmap. 

virtual IBitmapHandle Supported On: 

handle() const; PM 


Bitmap Copying 

Use these members to make a copy of the bitmap. 

Creates a copy of a bitmap. It is the caller's responsibility to delete the bitmap. 
This function is useful when you need to create a bitmap and "give it away" as in 
placing a bitmap on the clipboard. 

static IBitmapHandle 

copy( const IBitmapHandle& bitmapHandle); 


Exceptions 

IAccessError An error occurred while attempting to copy the bitmap. Refer to the 

exception text for specific error information. 


Supported On: 

PM 
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Bitmap Positioning 

Use these members to set and query the size and position of the bitmap. The bitmap position 
information is not used during drawing if you use drawOn member, which accepts position 
arguments. 

Sets the position of where the bitmap is drawn. 

virtual IGBitmap& 
moveTo( const IPoint& point); 

.Returns the position of where the bitmap is drawn 

virtual IPoint Supported On: 

position() const; PM 

Returns the size of the bitmap. 


Supported On: 

PM 


virtual ISize Supported On: 

size() const; PM 

Resizes the bitmap to the argument size. 


virtual IGBitmap& 
sizeTo( const ISize& newSize); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to resize the bitmap. Refer to the 
exception text for specific error information. 


Bitmap Transparency 

Use these members to control transparency when you draw a bitmap on a graphic context. Bits 
whose color is the same as the transparency color are not visible. The object under the bitmap is 
visible for these bits. Use transparency when you want to mask out a section of the bitmap with 
the color you set as the transparency color. 

Note: These members do not modify the actual bitmap data. 

hasT ransparentColor 

Returns true if a transparent color has been set; otherwise false is returned. 

virtual IBase: :Boolean Supported On: 

hasTransparentColor() const; PM 
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resetT ransparentColor 

Resets the bitmap so that no color is treated as transparent when drawing the bitmap. 

virtual IGBitmap& Supported On: 

resetTransparentColor(); PM 

setTransparentColor 

Sets the color to be treated as transparent when drawing the bitmap. 


virtual IGBitmap& 

setTransparentColor( const IColor& aColor); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the bitmap transparency color. 

Refer to the exception text for specific error information. 


transparentColor 

Returns the current Uansparent color. 


virtual IColor 
transparentColor() const; 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. 

IGBitmap 

| IGBitmap( const IBitmapHandl e& bitmapHandl e) ; Supported On: 

PM 

Use this function to consUuct a IGBitmap object from a IBitmapHandle. This is 
useful for draw-item events where the bitmap handle is supplied. 

bitmapHandle Handle to a bitmap. 

§ IGBitmap( unsigned long bitmapldentitier); Supported On: 

PM 


Use this function to consUuct a IGBitmap object from a resource identifier. The 
bitmap is loaded from the resource file bound to the executable of from the user 
resource dynamic link library. 
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bitmapldentifier Resouce identifier. 


0 IGBitmap( const IResourceId& resourceldenti tier); Supported On: 

PM 

Use this function to construct a IGBitmap object from a IResourceld object. This 
allows you to specify a resource identifier that exists in another resource library. 

resourceldentifier A IResourceld object. 

0 IGBitmap( const IString& imageFilename); Supported On: 

PM 

Use this constructor to create a IGBitmap object from an image file name. The 
image format (p. 648) is determined by the file extension of the image file name. 

imageFilename Name of the image file you want to load. 


g IGBitmap( const IString& imageFilename, Supported On: 

ImageFormat imageFormat); PM 

Use this function to construct a IGBitmap object from an image file name and an 
image file format. This constructor is identical to the previous constructor except that 
you explicitly state the image file format. This is useful when you want to load an 
image from a file that does not have a file extension that matches an extension for a 
given image format. Refer to Image Formats (p. 648) for the file extensions that are 
associated with an image format. 

imageFilename Name of the image file you want to load. 
imageFormat Type of image format. 


^ IGBitmap( const IGraphicContext& graphicContext, Supported On: 

const IRectangle& windowRectangle); PM 

Use this function to construct a IGBitmap object from a graphic context and a 
rectangle specifying an area of the graphic context in device space. 

graphicContext A IGraphicContext object. 

windowRectangle Area of the graphic context you want to create a bitmap of. 
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Q IGBitmap( const IGBitmap& bitmap. Supported On: 

const IRectangle& rectangle, PM 

long rasterOperation = normal); 

Use this function to construct a IGBitmap object from the rectangular portion of 
another IGBitmap object. You may optionally specify a raster operation that is used 
when the bitmap object is constructed. 

bitmap A reference to a IGBitmap object. 

rectangle Rectangle area of the bitmap to copy. 

rasterOperation Raster operation used when copying the bitmap. 

IGBitmap 

virtual 
'IGBitmapO ; 


Supported On: 

PM 


Drawing 

Use these members to render a bitmap object on a device. 


drawOn 

Q virtual IGBitmap& Supported On: 

drawOn( IGraphicContext& graphicContext, PM 

long rasterOperation); 

Draws the bitmap on the device associated with the graphic context. This function 
draws the bitmap at the bitmap's current position. You must specify a raster 
operation when using this function. 

Exceptions 

IAccessError An error occurred while attempting to draw the bitmap. Refer to the 

exception text for specific error information. 


2 virtual IGBitmap& Supported On: 

drawOn( IGraphicContext& graphicContext); PM 

Draws the bitmap on the device associated with the graphic context. This function 
draws the bitmap at the bitmap's current position with a normal raster operation. 
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Exceptions 

IAccessError An error occurred while attempting to draw the bitmap. Refer to the 

exception text for specific error information. 


g virtual IGBitmap& Supported On: 

drawOn( IGraphicContext& graphicContext, PM 

const IPoint& targetBottomLeft, 
const IPoint& targetTopRight, 
const IPoint& sourceBottomLeft, 
const IPoint& sourceTopRight, 
long rasterOperation = normal, 

CompressMode compressMode = ignore); 

Draws the bitmap on the device associated with the graphic context. You can shrink 
or stretch the bitmap when drawing the bitmap. The first pair of points allows you to 
specify a target rectangle where the bitmap is drawn; the second pair of points allows 
you to specify a rectangular area of the bitmap to draw into the target rectangle. You 
can optionally specify a compress mode and raster operation that will be used when 
you draw the bitmap. 

Exceptions 

IAccessError An error occurred while attempting to draw the bitmap. Refer to the 

exception text for specific error information. 


Modifying a Bitmap 

Use these members to modify the bitmap. The rotate functions are different from 
IGraphic::rotateBy in that the change to the bitmap is permanent. IGraphic::rotateBy modifies a 
model transform that is set before drawing the bitmap and is removed after the bitmap has been 
drawn and does not affect the actual bitmap data. The rotations are counterclockwise. 


reflectHorizontally 

Reflects the bitmap from left to right. 


virtual IGBitmap& 
reflectHorizontal ly(); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to reflect the bitmap. Refer to the 
exception text for specific error information. 


reflectVertically 

Reflects the bitmap from top to bottom. 
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virtual IGBitmap& 
reflectVertical ly(); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to reflect the bitmap. Refer to the 
exception text for specific error information. 


_Rotates the bitmap by 180 degrees counterclockwise. 


virtual IGBitmap& 
rotateByl8G(); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to rotate the bitmap. Refer to the 
exception text for specific error information. 


—Rotates the bitmap by 270 degrees counterclockwise. 


virtual IGBitmap& 
rotateBy270(); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to rotate the bitmap. Refer to the 
exception text for specific error information. 


—Rotates the bitmap by 90 degrees counterclockwise. 


virtual IGBitmap& 
rotateBy90(); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to rotate the bitmap. Refer to the 
exception text for specific error information. 


transposeXForY 

Transposes all X values for Y values. 


virtual IGBitmap& 
transposeXForY(); 


Supported On: 

PM 
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Exceptions 

IAccessError An error occurred while attempting to transpose the bitmap. Refer to the 

exception text for specific error information. 


View Option 

Use these members to specify an algorithm to use when the image data is converted to a bitmap. 
The viewing options are as follows: 

• raw 

Indicates not to use any algorithm when converting the image data to a bitmap. 

• errorDiffused 

Indicates that an error diffusion algorithm is used when converting the image data to a 
bitmap. The actual image data is not affected, only what you see on the screen. Error 
diffusion takes longer than halftoning, but the bitmap is generally sharper, especially when 
viewing .gif files. 

• halftoned 

Indicates that a halftone algorithm is used when converting the image data to a bitmap. The 
actual image data is not affected, only what you see on the screen. Coverting the image data 
using the halftoned algorithm is generally quicker than using the error diffusion algorithm. 

setViewOption 

Sets the method used to convert the image data to a bitmap, 
virtual IGBitmap& 

setViewOption( ViewOption viewOption = raw); 


Exceptions 

IAccessError An error occurred while attempting to change the view option. Refer to 

the exception text for specific error information. 


Supported On: 

PM 


—Returns the method used to convert the image data to a bitmap. 

virtual ViewOption Supported On: 

viewOption() const; PM 


Writing to a File 

Use these members to save the bitmap in any of the supported image file formats and query the 
type of the image format. 
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Returns the type of the bitmap image format. 


virtual ImageFormat Supported On: 

imageFormatO const; PM 

....Saves a bitmap to a file in any of the supported image file formats. If the specified 
file already exists, the file is overwritten. 


virtual IGBitmap& 

writeToFile( const IString& imageFi1ename, 
ImageFormat imageFormat); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to write the image file. Check the path 

and filename. 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Loading a Bitmap 

These static members load a bitmap from a resource file. 

...Loads bitmaps from resource files. If you use the default for the size argument, the 
bitmap is not resized. 


static unsigned long Supported On: 

loadBitmap( unsigned long bitmapldentitier, PM 

const IModuleHandl e& moduleHandle, 
const ISize& bitmapSize = ISize (0,0)); 


tryToLoadBitmap 

Load bitmaps from resource files. If you use the default for the size argument, the 
bitmap is not resized. This function differs from loadBitmap in that it does not 
throw an exception if the bitmap cannot be loaded. This allows you to attempt to 
load a bitmap without having to catch an exception if the load fails. 

static unsigned long Supported On: 

tryToLoadBitmap ( unsigned long bi tmapldenti fi er, PM 

const IModuleHandle& moduleHandle, 
const ISize& bitmapSize = ISize ( 0 , 0 )); 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Public Data 

Common Raster Operations 

The following list defines 16 common raster operations for combining a source bitmap, 
destination bitmap (screen), and the current set pattern. You can specify these raster options 
when drawing a bitmap. 

black 0 

notSourceErase '(Source I Destination) 
halftone (Pattern I Source) 
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invert 

"Source 

sourceErase 

Source & 'Destination 

destlnvert 

'Destination 

patternlnvert 

Pattern A Destination 

sourcelnvert 

Source A Destination 

sourceAnd 

Source & Destination 

mergePaint 

"Source 1 Destination 

mergeCopy 

Pattern & Source 

normal 

Source 

sourcePaint 

Source 1 Destination 

patternCopy 

Pattern 

patternPaint 

Pattern 1 "Source 1 Destination 

white 

1 


The target bitmap is black. 

static const long Supported On: 

black; PM 

..The target bitmap is the inverse of the destination (screen) bitmap. 


static const long 
destlnvert; 


Supported On: 

PM 


halftone 


static const long Supported On: 

halftone; PM 

The target bitmap is determined by inverting the source bitmap. 


static const long Supported On: 

invert; PM 

_The target bitmap is determined by ANDing the current pattern set with the source 
bitmap. 
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static const long Supported On: 

mergeCopy; PM 

_The target bitmap is determined by ORing the destination (screen) bitmap with the 
inverse of the source bitmap. 


static const long Supported On: 

mergePaint; PM 

The target bitmap is the source bitmap. 


static const long 
normal; 


Supported On: 

PM 


notSourceErase 

The target bitmap is determined by ANDing the inverse of the destination (screen) 
bitmap with the inverse of the source bitmap. 


static const long Supported On: 

notSourceErase; PM 

_The target bitmap is the current pattern set. 


static const long Supported On: 

patternCopy; PM 

_The target bitmap is determined by XORing the current pattern set with the 
destination (screen) bitmap. 


static const long Supported On: 

patternlnvert; PM 

_The target bitmap is determined by ORing the current pattern set with the 
destination (screen) bitmap with the inverse of the source bitmap. 


static const long Supported On: 

patternPaint; PM 

.The target bitmap is determined by ANDing the destination (screen) bitmap with the 

source bitmap. 


static const long 
sourceAnd; 


Supported On: 

PM 
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__The target bitmap is determined by ANDing the inverse of the destination (screen) 
bitmap with the source bitmap. 

static const long Supported On: 

sourceErase; PM 

__The target bitmap is determined by XORing the destination (screen) bitmap with the 
source bitmap. 


static const long Supported On: 

sourcelnvert; PM 

__The target bitmap is determined by ORing the destination (screen) bitmap with the 
source bitmap. 


static const long Supported On: 

sourcePaint; PM 

.. The target bitmap is white. 


static const long Supported On: 


white; 


PM 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 



CompressMode 

CompressMode { 
and, 
or, 

ignore 

}; 


The compress mode allows to specify how a bitmap will stretched if the bitmap is 
stretched when drawn. The compress mode values are: 

and 

Compresses the bitmap as necessary, using a logical OR operation on the 
eliminated rows and columns. This is useful for preserving the foreground 
when foreground bits are "0" and the background bits are "1". 
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or 

Compresses the bitmap as necessary, using a logical OR operation on the 
eliminated rows and columns. This is useful for preserving the foreground 
when foreground bits are "1" and the background bits are "0". 

ignore 

Compresses the bitmap as necessary, but ignores any elimanted rows or 
columns. This is useful for color bitmaps where the results of combining pels 
of different colors are unpredictable. 


ImageFormat { 

Bitmap, GIF, PCX, TIFF, Targa, 

Amiga, XBM, PSEG 

}; 


The IGBitmap class allows you to load and save bitmaps in several popular image 
file formats. There are two constructors that allow you to create a bitmap from an 
image file. You can use IGBitmap::writeToFile to save a bitmap in any of the 
supported image file formats. The image formats this class supports are: 

OS/2 and Windows Bitmaps 

The file extensions .BMP, .VGA, .BGA, .RLE, .DIB, .RL4, and .RL8 are 
recognized as OS/2 1.1, 1.2, 2.0 or Windows 3.0 bitmaps. The newer 
multimedia Windows bitmap format that allows 16 and 32 bits-per-plane is not 
supported. The files are written in OS/2 2.0/Windows 3.0 format. 

CompuServe Graphics Interchange Format 

The .GIF file extension is recognized as a GIF file. 

ZSoft PC Paintbrush Image File Format 

The .PCX file extension is recognized as a Paintbrush file. 

Microsoft/Aldus Tagged Image File Format 

The .TIF and .TIFF file extensions are recognized as TIFF files. 

Truevision Targa/Vista Bitmap 

The file extensions .TGA, .VST, and .AFI are recognized as Targa/Vista files. 
This class only supports 8 bit-per-plane and 24 bit-per-plane images. 

Amiga IFF/ILBM Interleaved Bitmap Format 

The file extensions .IFF and .LBM are recognized as interleaved bitmap files. 

X Windows Bitmap 

The .XBM file extension is recognized as a X Bitmap file. This class supports 
X10 and XI1 lbpp bitmaps. Some .XBM files with text strings inside look to 
be sprites or icons and are not supported. 
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IBM Printer Page Segment 

The following file extensions .PSE, .PSEG, .PSEG38PP and .PSEG3820 are 
recognized as PSEG files. PSEG files are used to include image data in 
BookMaster documents. PSEG files only contain 1 bit-per-plane, which is 
always ink on paper, ie: black on white. 


ViewOption { 
raw, 

errorDiffused, 
halftoned 
}; 


The viewing options allow you to specify an algorithm to use when the image data is 
converted to a bitmap. The viewing options are: 

• raw 

This indicates not to use any algorithm when converting the image data to a 
bitmap. 

• errorDiffused 

Indicates that an error diffusion algorithm is used when converting the image data 
to a bitmap. The actual image data is not affected, only what you see on the 
screen. Error diffusion takes longer than halftoning, but the bitmap is generally 
sharper, especially when viewing .gif files. 

• halftoned 

Indicates that a halftoning algorithm is used when converting the image data to a 
bitmap. The actual image data is not affected, only what you see on the screen. 
Halftoning is generally quicker than error diffusion. 

Note: Error diffusion and halftoning have little affect when used on OS/2 and 
Windows bitmaps. 
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IBase 

IVBase 

IGraphic 

IGPie 

IGChord 


_.None. 


—igpie.hpp 

Member 

Page 

Constructor 

651 

drawOn 

651 

'IGChord 

651 


The IGChord class is a graphic object class that allows you to create a 
two-dimensional closed figure created from the chord of an ellipse. The IGChord can 
be filled, framed, or filled and framed. The rectangle you specify in the constructor 
is the enclosing rectangle of an ellipse. The start angle and sweep angles specify a 
chord section of this ellipse. 

When you draw a IGChord, the following graphic bundle attributes affect its 
appearance: 

• Draw operation 

• Pen color 

• Fill color 

• Background color 

• Mix mode 

• Background mix mode 

• Pen width 

• Pen type 

• Pen ending style 

• Pen joining style 

• Pen pattern 

• Fill pattern 

• Pattern origin 
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Public Functions 
Constructors 

You can construct, destruct, and copy objects of this class. 


IGChord 

Q IGChord( const IRectangle& rectangle. Supported On: 

double startAngle, PM 

double sweepAngle); 

Use this function to construct a IGChord object from an IRectangle object specifying 
the enclosing rectangle, a start angle, and a sweep angle. The sweep angle is drawn 
counterclockwise. The rectangle specifies an enclosing rectangle of an ellipse with 
the start and sweep angles defining a chord section of this ellipse. 

rectangle Enclosing rectangle of an ellipse. 

startAngle Start angle of the ellipse. 

sweepAngle Sweep angle specifying a chord shaped section of the ellipse. 


§ IGChord( const IGChord& chord); Supported On: 

PM 

Use this function to construct a IGChord object from another IGChord object. 
chord A reference to a IGChord object. 

"IGChord 

virtual 

'IGChord(); 

Drawing 

Use these members to render a IGChord object on a device. 

Draws the IGChord object on the device associated with the graphic context. 

virtual IGChord& Supported On: 

drawOn( IGraphicContext& graphi cContext); PM 


Supported On: 

PM 
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Inherited Public Functions 


IGPie 

drawOn 

operator = 

setStartAngle 

enclosingRect 

operator == 

setSweepAngle 

operator != 

setEnclosingRect 

startAngle 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

remo veGraphicB undle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicB undle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IGEIlipse 


IBase 

IVBase 

IGraphic 

IGEllipse 


_.None. 

_ igelipse.hpp 


Member 

Page 

Member 

Page 

Constructor 

654 

operator = 

655 

drawOn 

655 

operator == 

654 

enclosingRect 

655 

setEnclosingRect 

656 

operator != 

654 

“IGEllipse 

655 


Objects of this class are used to draw two-dimensional ellipses. An IGEllipse can be 
filled, framed, or filled and framed. 

When you draw an IGEllipse, the following bundle attributes affect its appearance: 

• Draw operation 

• Pen color 

• Fill color 

• Background color 

• Mix mode 

• Background mix mode 

• Pen width 

• Pen type 

• Pen pattern 

• Fill pattern 

• Pattern origin 


Public Functions 
Comparisons 

Use these members to compare two IGEllipse objects. 
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_Returns true if the ellipses are not identical (includes the graphic bundle attributes 
and the transform matrix). 

I Base:: Boolean Supported On: 

operator ! = ( const IGEllipse& ellipse) const; PM 

-.Returns true if the ellipses are identical (includes the graphic bundle attributes and 
the transform matrix). 

I Base:: Boolean Supported On: 

operator ==( const IGEllipse& ellipse) const; PM 


Constructors 

You can construct, destruct, copy, and assign objects of the IGEllipse class. 

IGEllipse 

[] IGEl 1 ipse( const IGEllipse& ellipse); Supported On: 

PM 

Use this function to construct a IGEllipse object from another IGEllipse object. 
ellipse A Reference to a IGEllipse object. 

2 IGEl 1 ipse( const IRectangle& rectangle); Supported On: 

PM 

Use this function to construct a IGEllipse object from a IRectangle object specifying 
the enclosing rectangle of the ellipse. 

rectangle A IRectangle object specifying the enclosing rectangle of the ellipse. 

g IGEUipse( const IPoint& point, Supported On: 

unsigned long radius); PM 

Use this function to construct a IGEllipse object from a IPoint object specifying the 
center of the ellipse and a radius indicating the length of the major and minor axes. 

point Center point of the ellipse. 

radius Radius of the ellipse. 
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0 IGEl 1 i pse{ const IPoint& point. Supported On: 

unsigned long xRadius, PM 

unsigned long yRadius); 

Use this function to construct a IGEllipse object from a IPoint object specifying the 
center of the ellipse and two values indicating the length of the horizontal and vetical 
radii respectively. 

point Center point of the ellipse. 

xRadius Horizontal radius of the ellipse. 
yRadius Vertical radius of the ellipse. 

_ Use this function to assign a IGEllipse object to another IGEllipse object. 

IGEl 1 i pse& Supported On: 

operator =( const IGEl 1 ipse& ellipse); PM 

"IGEllipse 


virtual Supported On: 

'IGEUipseO; PM 


Drawing 

Use these members to render an IGEllipse object on a device. 

Draw the ellipse on the device associated with the graphic context. 


virtual IGEl 1 ipse& 

drawOn( IGraphicContext& graphicContext); 


Supported On: 

PM 


Enclosing Rectangle 

Use these members to specify a rectangle that contains an ellipse. 


enclosingRect 

Returns the enclosing rectangle that the IGEllipse is contained within. 


virtual IRectangle 
enclosingRect() const; 


Supported On: 

PM 
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setEnclosingRect 

Sets the enclosing rectangle that the IGEllipse is contained within. 


virtual IGE11ipse& 

setEnclosingRect( const IRectangle& rectangle); 


Supported On: 

PM 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

IGraphic 

IGLine 


_.None. 


_igline.hpp 

Member 

Page 

Constructor 

658 

centerPoint 

659 

drawOn 

659 

endingPoint 

659 

operator != 

657 

operator = 

658 


Member 
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operator == 

658 

setEndingPoint 

659 

setStartingPoint 

659 

slope 

659 

startingPoint 

659 

“IGLine 

658 


The IGLine class is a graphic object class that allows you to create two-dimensional 
line segments. 

When you draw a IGLine, the following graphic bundle attributes affect its 
appearance: 

• Pen color 

• Mix mode 

• Pen width 

• Pen type 

• Pen ending style 


Public Functions 
Comparisons 

Use these members to compare two IGLine objects. 

_ Returns true if the lines are not identical (includes the graphic bundle attributes and 
the transform matrix). 
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I Base:: Boolean Supported On: 

operator ! = ( const IGLine& line) const; PM 

..Returns true if the lines are identical (includes the graphic bundle attributes and the 
transform matrix). 


IBase::Boolean 

operator ==( const IGLine& line) const; 


Supported On: 

PM 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 


[] IGLine( const IPoint& startingPoint, Supported On: 

const IPoint& endingPoint); PM 

Use this function to construct a IGLine object from two IPoint objects indicating the 
starting and ending points of the line. 

startingPoint Starting point of the line. 

endingPoint Ending point of the line. 


g IGLine( const IGLine& line); Supported On: 

PM 

Use this function to construct a IGLine object from another IGLine object. 
line A reference to a IGLine object. 

. Use this function to assign a IGLine object to another IGLine object. 

IGLine& Supported On: 

operator =( const IGLine& line); PM 


"IGLine 


virtual 
'IGLineO; 


Supported On: 

PM 
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Data Access 

Use these members to query and set the data points of the line as well as query the line's slope. 
_ Returns the center point of the line segment. 

virtual IPoint 
centerPoint() const; 

_ Returns the ending point of the line segment. 

virtual IPoint 
endingPoint() const; 

setEndingPoint 

Sets the ending point of the line segment, 
virtual IGLine& 

setEndingPoint( const IPoint& point); 

setStartingPoint 

Sets the starting point of the line segment, 
virtual IGLine& 

setStartingPoint( const IPoint& point); 

Returns the slope of the line segment (rise over run) 

double 

slope() const; 

.. Returns the starting point of the line segment. 

virtual IPoint 

startingPoint() const; 


Drawing 

Use these members to render a IGLine object on a device. 

Draws the line segment on the device associated with the graphic context. 

virtual IGLine& Supported On: 

drawOn( IGraphicContext& graphicContext); PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

remo veGraphicB undle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicB undle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

IGraphic 

IGList 


_.None. 


_iglist.hpp 


Member 

Page 

Member 

Page 

Constructor 

663 

isIGList 

665 

addAsFirst 

662 

lastGraphic 

665 

addAsLast 
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numberOfGraphics 

665 

addAsNext 

662 

removeAll 

665 

addAsPrevious 

662 

remove AllWithld 

666 

addAtPosition 

662 

removeAt 

666 

bottomGraphicUnderPoint 

664 

removeAtPosition 

666 

boundingRectAt 

664 

removeFirst 

666 

drawOn 

663 

removeLast 

666 

firstGraphic 

664 

replaceAt 

663 

graphicAt 

665 

sort 

666 

graphicAtPosition 

665 

topGraphicUnderPoint 

664 

isEmpty 

665 

“IGList 

663 


The IGList class is an ordered collection of IGraphic objects. The IGraphic objects 
are arranged so that each IGList has a first and a last IGraphic object, each IGraphic 
object except the last has a next IGraphic object, and each IGraphic object but the 
first has a previous IGraphic object. 

An IGList allows you to group simple IGraphic objects to compose a complex 
picture. At any time you can add additional IGraphic objects to the IGList or remove 
any IGraphic objects from it. You can also add the same IGraphic object to the list 
multiple times to replicate part of a picture. 

Because IGList inherits from IGraphic, you can add an IGList to an IGList. You can 
also use any of the transform functions inherited from IGraphic on an IGList. 
Transforms applied to an IGList affect all IGraphic objects in the IGList. You can 
easily construct complex pictures and transform them as a single entity. 
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When you draw a IGList, it iterates through the graphic objects contained in the list. 
IGList recursively calls the drawOn function for all nested IGLists. 

When you draw an IGList, the attributes you use to draw the graphic objects 
contained in the list are those of the graphic bundle applied to the IGList with one 
exception. When a graphic object contains a graphic bundle that has the same 
attributes set, the graphic object's bundle attributes override the IGList's graphic 
bundle attributes. 


Public Functions 
Adding Graphic Objects 

Use these members to add graphic objects to an IGList object. 
_ Adds a graphic object as the first item in the list. 


virtual IGList& Supported On: 

addAsFirst( IGraphic& graphic); PM 

-Adds a graphic object as the last item in the list. 


virtual IGList& Supported On: 

addAsLast( IGraphic& graphic); PM 

—Adds a graphic object directly after the cursor location. 


virtual IGList& 

addAsNext( const Cursor& cursor, 
IGraphic& graphic); 


Supported On: 

PM 


addAsPrevious 

Adds a graphic object directly before the cursor location. 


virtual IGList& 

addAsPrevious( const Cursor& cursor, 
IGraphic& graphic); 


Supported On: 

PM 


addAtPosition 

Adds a graphic object at the 0-based offset from the beginning of the list. 


virtual IGList& 

addAtPosition( unsigned long position, 
IGraphic& graphic); 


Supported On: 

PM 
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Replaces a graphic object at the cursor location. 


virtual IGList& 

replaceAt( const Cursor& cursor, 
IGraphic& graphic); 


Supported On: 

PM 


Constructors 

You can construct, destruct, and copy objects of this class. 


IGList 


Q IGList(); Supported On: 

PM 

Use this function to construct a IGList object. The list is initially empty. 

g IGList( IGraphic& graphic); Supported On: 

PM 

Use this function to construct a IGList object from a IGraphic object. The object is 
added to the list. 

graphic A reference to a IGraphic object. This graphic is added to the list. 

g IGLi st ( const IGLi st& list); Supported On: 

PM 

Use this function to construct a IGList object from another IGList object. A copy of 
the graphic object references is created. 

list A reference to a IGList object. All IGraphic objects in list are added to 

the new IGList. 

IGList 

virtual 
'IGLi st (); 

Drawing 

Use these members to render the graphic objects contained in an IGList on a device. 

...Iterates over the ordered collection calling each graphic object's drawOn function. 


Supported On: 

PM 
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virtual IGI_ist& 

drawOn( IGraphicContext& graphicContext); 


Supported On: 

PM 


Hit Testing 

Use these members to determine if a point is contained within one of the graphic objects 
contained in the IGList. 

Note: If you want to determine if more than one object is under a point, construct a Cursor 
object, which iterates through all objects that are under a specified point. 


bottomGraphicUnderPoint 

Returns the bottommost graphic object under the point specified. If a graphic object 
is not under the point specified, a null pointer is returned. 


virtual IGraphic* 

bottomGraphicllnderPoint( const IPoint& point, 

IGraphicContext& graphicContext); 


Supported On: 

PM 


topGraphicUnderPoint 

Returns the topmost graphic object under the point specified. If a graphic object is 
not under the point specified, a null pointer is returned. 


virtual IGraphic* 

topGraphicUnderPoint( const IPoint& point, 

IGraphicContext& graphicContext); 


Supported On: 

PM 


Querying the List 

Use these members to query list information and to retrieve the graphic objects contained in the 
list. 

boundingRectAt 

Returns the smallest rectangle enclosing the graphic object at the cursor location. Use 
this function with a cursor constructed to locate objects under the mouse. The 
bounding rectangle returned takes into account cummulative transformations that may 
be set prior to drawing a graphic object in the list. 

virtual IRectangle Supported On: 

boundingRectAt( const Cursor& cursor) const; PM 

Returns a pointer to the first graphic object in the list. If the list is empty, a null 
pointer is returned. 
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virtual IGraphic* Supported On: 

firstGraphic() const; PM 

.Returns a reference to the graphic object at the cursor location. 


virtual IGraphic& Supported On: 

graphicAt( const Cursor& cursor) const; PM 

graphicAtPosition 

Returns a reference to the graphic object at the given position in the list. Position 1 
specifies the first graphic object. 


virtual IGraphic& Supported On: 

graphicAtPosition( unsigned long position) const; PM 

...Returns true if the list is empty. 


virtual I Base:: Boolean Supported On: 

isEmptyQ const; PM 

Returns true if the graphic object at the cursor location is an IGList. 


virtual I Base:: Boolean Supported On: 

isIGList( const Cursor& cursor) const; PM 

—Returns a pointer to the last graphic object in the list. If the list is empty, a null 
pointer is returned. 


virtual IGraphic* Supported On: 

lastGraphic() const; PM 

numberOfGraphics 

Returns the count of the number of graphic objects in the list. 


virtual unsigned long 
numberOfGraphics() const; 


Supported On: 

PM 


Removing Graphic Objects 

Use these members to remove graphic objects from the IGList object. 
-Removes all graphic objects from the list. 
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virtual IGList& 
removeAl1(); 


Supported On: 

PM 


removeAHWithld 

Removes all graphic objects that have the specified identifier. 

virtual IGList& Supported On: 

removeAllWithldj unsigned long identifier); PM 

Removes the graphic object at the cursor location. 


virtual IGList& Supported On: 

removeAt( const Cursor& cursor); PM 

removeAtPosition 

Removes the graphic object at the 0-based offset from the beginning of the list. 


virtual IGList& Supported On: 

removeAtPosition( unsigned long position); PM 

—Removes the first graphic object in the list. 

virtual IGList& 
removeFirst (); 

—Removes the last graphic object in the list. 

virtual IGList& Supported On: 

removeLast(); PM 


Supported On: 

PM 


Reordering the List 

Use these members to reorder the graphic objects in the IGList. 

Reorders the graphics object contained in the graphic list. You need to write a C 
function with the following declaration: 

long MyGraphicCompare( IGraphic& graphic!., IGraphic& graphic2 ) 

{ 

} 


The function should return a long value: 


Less than 0 
0 

Greater than 0 


The first object is less than the second object. 
The first object is equal to the second object. 

The first object is greater than the second object. 


666 Open Class Library Reference 



IGList 


The graphic objects are reordered in ascending order. 


virtual IG L ist& Supported On: 

sort( long ( * comparisonFunction ) ( IGraphic * const & graphicl , PM 

IGraphic * const & graphic2 )); 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

remo veGraphicB undle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Nested Classes 

IGList contains the following nested classes: 
IGList::Cursor (see page 669) 
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IGList::Cursor 


IBase 
IVBase 
IGList:: Cursor 


_.None. 


_iglist.hpp 


Member 

Page 

Member 

Page 

Constructor 

670 

setToLast 

671 

Cursor 

670 

setToNext 

671 

invalidate 

670 

setToPrevious 

671 

is Valid 

671 

“Cursor 

670 

setToFirst 

671 




The IGList: :Cursor class is used to iterate through graphic objects contained in an 
IGList. The Cursor class has three constructors that control how to iterate through 
the IGList. The class iterates through top-level objects only. If you nest an IGList 
inside an IGList, the cursor does not iterate through the graphic objects contained 
within the nested IGList. 

The Cursor class iterates through all objects in an IGList, iterates through all objects 
with a specified identifier, or provides hit testing by iterating through all objects that 
are under a specified point. If you iterate by identifier, a match is determined by 
querying the object's identifier value that is set by the IGraphic::setId function. 

If you want to iterate through nested IGLists, you can obtain a reference to the nested 
IGList (or any other graphic object in the list) by calling IGList: :graphicAtPosition. 
You can then create another cursor for this list. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 
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Cursor 


[J Cursor( const IGLi st& list); Supported On: 

PM 

Use this function to construct a IGList::Cursor object from a IGList object. The 
cursor iterates through all graphic objects contained in the IGList. 

list IGList to cursor through. 

| Cursor( const IGLi st& list. Supported On: 

unsigned long objectldentifier); PM 

Use this function to construct a IGList::Cursor object from a IGList object and am 
object identifier. The cursor iterates through graphic objects that have the specified 
object identifier. 

list IGList to cursor through. 

objectldentifier Graphic objects identifier. 

2 Cursor( const IGList& list, 

IGraphicContext& graphicContext, 
const IPoint& hitPoint); 

Use this function to construct a IGList::Cursor object from a IGList object, a 
IGraphicContext object and a IPoint object. The cursor iterates through graphic 
objects that intersect or contain the point specified. 

list IGList to cursor through. 

graphicContext Graphic context used to determine a graphic objects location. 

hitPoint Position of the center of the hit aperture. 

Cursor 


Supported On: 

PM 


virtual 
"CursorO; 


Supported On: 

PM 


Cursor Positioning 

Use these members to move the cursor through the list of graphic objects and to check the 
validity of the cursor. 

_Marks the cursor as invalid. 
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virtual void Supported On: 

inval idate(); PM 

Returns true if the cursor is in a valid area. 


virtual I Base:: Bool ean Supported On: 

isValidQ const; PM 

.Resets the cursor position to the first graphic object in the list. 


virtual I Base:: Bool ean Supported On: 

setToFirst(); PM 

.Resets the cursor position to the last graphic object in the list. 


virtual I Base:: Bool ean Supported On: 

setToLast(); PM 

^ Advances the cursor position to the next graphic object in the list. 


virtual IBase::Boolean 
setToNext(); 


Supported On: 

PM 


setToPrevious 

Advances the cursor position to the previous graphic object in the list. 


virtual IBase::Boolean 
setToPrevious(); 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



672 Open Class Library Reference 



IGPie 



IGPie 


IBase 

IVBase 

IGraphic 

IGPie 


IGChord 


—igpie.hpp 


Member 
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drawOn 
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enclosingRect 
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operator != 
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operator = 
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operator == 
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Member 
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setEnclosingRect 

675 

setStartAngle 

676 

setSweepAngle 

676 

startAngle 

676 

sweepAngle 

676 

"IGPie 

675 


The IGPie class is a graphic object class that allows you to create a two-dimensional 
pie slice of an ellipse. The IGPie can be filled, framed or filled and framed. The 
rectangle you specify in the constructor is the enclosing rectangle of an ellipse. The 
start angle and sweep angles specify a pie section of this ellipse. 

When you draw a IGPie, the following bundle attributes affect its appearance: 

• Draw operation 

• Pen color 

• Fill color 

• Background color 

• Mix mode 

• Background mix mode 

• Pen width 

• Pen type 

• Pen ending style 

• Pen joining style 

• Pen pattern 

• Fill pattern 

• Pattern origin 
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Public Functions 
Comparisons 

Use these members to compare two IGPie objects. 

_ Returns true if the pies are not identical (includes the graphic bundle attributes and 
the transform matrix). 

I Base:: Boolean Supported On: 

operator ! = ( const IGPie& pie) const; PM 

_ Returns true if the pies are identical (includes the graphic bundle attributes and the 
transform matrix). 

I Base:: Boolean Supported On: 

operator ==( const IGPie& pie) const; PM 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 


IGPie 


[J IG Pi e( const IRectangle& rectangle, Supported On: 

double startAngle, PM 

double sweepAngle); 

Use this function to construct a IGPie object from a IRectangle object specifying the 
enclosing rectangle, a start angle, and a sweep angle. The sweep angle is drawn 
counter clockwise. The rectangle specifies an enclosing rectangle of an ellipse with 
the start and sweep angles defining an pie section of this ellipse. 

rectangle Enclosing rectangle of an ellipse. 

startAngle Start angle of the ellipse. 

sweepAngle Sweep angle specifying a pie shaped section of the ellipse. 

g IGPie( const IGPie& pie); Supported On: 

PM 


Use this function to construct a IGPie object from another IGPie object. 
pie A reference to a IGPie object. 
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Use this function to assign a IGPie object to another IGPie object. 


IG Pi e& Supported On: 

operator =( const IGPie& pie); PM 


IGPie 


virtual Supported On: 

"IGPieO; PM 


Drawing 

Use these members to render an IGPie object on a device. 

Draws the pie-shaped figure on the device associated with the graphic context. 


virtual IGPie& 

drawOn( IGraphicContext& graphicContext); 


Supported On: 

PM 


Enclosing Rectangle 

Use these members to specify a rectangle that contains an ellipse. The start and sweep angle 
define a pie-shaped section of this ellipse. 


enclosingRect 

Returns the enclosing rectangle of the ellipse that the pie is a section of. 

virtual IRectangle Supported On: 

enclosingRect() const; PM 

setEnclosingRect 

Sets the enclosing rectangle of an ellipse. The pie is a section of this ellipse. 

virtual IGPi e& Supported On: 

setEnclosingRect( const IRectangle& rectangle); PM 


Start and Sweep Angles 

Use these members to define a pie-shaped section of an ellipse contained within the enclosing 
rectangle. The start and sweep angles are expressed in degrees. 
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setStart Angle 

Sets the start angle of the pie (0 <= angle <= 360). 

virtual IGP ie& Supported On: 

setStartAngle( double startAngle); PM 


setSweep Angle 

Sets the sweep angle of the pie (0 <= angle <= 360). The sweep angle is drawn in a 
counterclockwise direction. 


virtual IGPi e& Supported On: 

setSweepAngle( double sweepAngle); PM 

.Returns the start angle of the pie. 


virtual double 
startAngle() const; 

_Returns the sweep angle of the pie. 


virtual double Supported On: 

sweepAngle() const; PM 


Supported On: 

PM 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

remo veGraphicB undle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicB undle 

transformMethod 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IGPolygon 


IBase 

IVBase 

IGraphic 

IGPolyline 

IGPolygon 


_.None. 

_ igpyline.hpp 
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The IGPolygon class is a graphic object class that allows you to create a 
two-dimensional closed figure from a series of line segments. The series of line 
segments is drawn starting from the first point and connecting all remaining points. 

If the first and last points are not the same, this class draws a line from the last point 
to the first point to close the figure. 

You can optionally specify a fill mode to use when drawing the polygon. The default 
fill mode is alternate. Refer to the operating system graphic programming reference 
for an explanation of these fill modes. 

When you draw a IGPolygon, the following graphic bundle attributes affect its 
appearance: 

• Draw operation 

• Pen color 

• Fill color 

• Background color 

• Mix mode 

• Background mix mode 

• Pen width 

• Pen type 

• Pen ending style 
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• Pen joining style 

• Pen pattern 

• Fill pattern 

• Pattern origin 


Public Functions 
Comparisons 

Use these members to compare two IGPolygon objects. 

_ Returns true if the polygons are not identical (includes the graphic bundle attributes 
and the transform matrix). 

Boolean Supported On: 

operator ! = ( const IGPolygon& polygon) const; PM 

_ Returns true if the polygons are identical (includes the graphic bundle attributes and 
the transform matrix). 

Boolean Supported On: 

operator ==( const IGPolygon& polygon) const; PM 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 

IGPolygon 

Q IGPolygon( const IPointArray& pointArray); Supported On: 

PM 

Use this function to construct a IGPolygon object from a IPointArray (Vol. I) object. 
The polygon is constructed by drawing line segments starting from the first point 
connecting the remaining points. If the first and last points are not the same, a line is 
drawn from the first point to the last point to close the figure. 

pointArray Array of data points. 

@ IGPolygon( const IGPolygon& polygon); Supported On: 

PM 


Use this function to construct a IGPolygon from another IGPolygon object. 
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polygon A reference to a IGPolygon object. 


_.Use this function to assign a IGPolygon object to another IGPolygon object. 

IGPolygon& Supported On: 

operator =( const IGPolygon& polygon); PM 


IGPolygon 


virtual 

'IGPolygon(); 


Supported On: 

PM 


Drawing 

Use these members to render an IGPolygon object on a device. 

Draws the polygon on the device associated with the graphic context. 

virtual IGPolygon& Supported On: 

drawOn( IGraphicContext& graphicContext); PM 


Fill Mode 

Use these members to query and set the fill mode that you use when drawing the polygon. 
Returns the fill mode used when drawing the polygon. 


virtual Fill Mode Supported On: 

fillModeQ const; PM 

—Sets the fill mode used when you draw the polygon. 


virtual IGPolygon& 
setFiUMode( Fill Mode fillmode); 


Supported On: 

PM 


Inherited Public Functions 


IGPolyline 

addPoint 

operator != 

pointArray 

drawOn 

operator = 

removePoint 

insertPoint 

operator == 

reversePoints 
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IGPolyline 

numberOfPoints 

point 

setPoint 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Fill Mode { 
alternate, 
winding 
}; 
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IGPolyline 
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IVBase 

IGraphic 

IGPolyline 


IGPolygon 


_ igpyline.hpp 


Member 

Page 

Member 

Page 

Constructor 

683 

point 

684 

addPoint 

684 

pointArray 

684 

drawOn 

685 

removePoint 

684 

insertPoint 

684 

reversePoints 

684 

numberOfPoints 

684 

setPoint 

684 

operator != 

683 

setPoints 

685 

operator = 

683 

'IGPolyline 

683 

operator == 

683 




The IGPolyline class is a graphic object class that allows you to create a series of 
two-dimensional line segments. The series of line segments is drawn starting from 
the first point and connecting all remaining points. 

When you draw a IGPolyline, the following graphic bundle attributes affect its 
appearance: 

• Pen color 

• Mix mode 

• Pen width 

• Pen type 

• Pen ending style 


Public Functions 
Comparisons 

Use these members to compare two IGPolyline objects. 
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^Returns true if the polylines are not identical (includes the graphic bundle attributes 
and the transform matrix). 

IBase: :Boolean Supported On: 

operator ! = ( const IGPolyline& polyline) const; PM 

-.Returns true if the polylines are identical (includes the graphic bundle attributes and 
the transform matrix). 

IBase: :Boolean Supported On: 

operator ==( const IGPolyline& polyline) const; PM 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 

IGPolyline 

Q IGPol yl i ne ( const IPointArray& pointArray); Supported On: 

PM 

Use this function to construct a IGPolyline object from a IPointArray (Vol. I) object. 
The polyline is constructed by drawing line segments starting from the first point and 
connecting the remaining points. 

pointArray Array of data points. 

@ IGPol yl i ne ( const IGPol yl i ne& polyline); Supported On: 

PM 

Use this function to construct a IGPolyline object from another IGPolyline object. 
polyline A reference to a IGPolyline object. 

- Use this function to assign a IGPolyline object to another IGPolyline object. 

IGPol yl ine& Supported On: 

operator =( const IGPol yl i ne& polyline); PM 

"IGPolyline 


virtual 

'IGPolyline(); 


Supported On: 

PM 
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Data Points 

Use these members to add, modify, and remove the points that define the polyline. 

-Adds a point to the end of the polyline. 

virtual IGPolyline& Supported On: 

addPoint( const IPoint& point); PM 

- Adds a point to the polyline at the location before the specified index. The index is 
0-based. 


virtual IGPolyline& 
insertPoint( unsigned long index, 
const IPoint& point); 


Supported On: 

PM 


numberOfPoints 

Returns the number of points defining the polyline. 


virtual unsigned long Supported On: 

numberOfPoints() const; PM 

Returns a constant reference to the point at the specified index. The index is 
0-based. 


const I Poi nt& Supported On: 

point( unsigned long index) const; PM 

-Returns a constant reference to the array of points defining the polyline. 


const IPointArray& Supported On: 

pointArray() const; PM 

-.Removes a point for the polyline at the specified index. The index is 0-based. 


virtual IGPolyline& 
removePoint( unsigned long index); 


Supported On: 

PM 


reversePoints 

Reverses all points in the polyline. The first point becomes the last and so on. 


virtual IGPol yl i ne& Supported On: 

reversePoints(); PM 

...Sets the point at the specified index to the argument point. The index is 0-based. 
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virtual IGPolyline& 

setPoint( unsigned long index, 
const IPoint& point); 

.. Sets the points used to define the polyline. 


Supported On: 

PM 


virtual IGPolyline& 

setPoints( const IPointArray& pointArray); 


Supported On: 

PM 


Drawing 

Use these members to render an IGPolyline object on a device. 

Draws the polyline on the device associated with the graphic context. 


virtual IGPolyl ine& 

drawOn( IGraphicContext& graphicContext); 


Supported On: 

PM 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Functions 

IGraphic 

operator != operator = 

Inherited Protected Data 

IBase 

recoverable unrecoverable 
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IGraphic is an abstract base class that provides common behavior for all 
two-dimensional graphic classes. The common behavior includes bounding rectangle 
information, accessing bundle attributes, transforming a graphic object, detecting if a 
graphic object has been selected (hit testing), and identifying a graphic object. 

An IGraphic object can optionally contain an IGraphicBundle and an 
ITransformMatrix. You can set a graphic bundle on a graphic object so that the 
attributes set in the bundle are used when you draw a graphic object. If you use any 
of the world transform functions or set a transform matrix on a graphic object, then 
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the transform matrix contained in the graphic object is used when you draw a graphic 
object. 

The drawOn function is a pure virtual function that is overridden by all classes 
derived from IGraphic. This function provides the drawing operations necessary for 
rendering a graphic object on a device. 


Public Functions 
Bounding Rectangle 

Use these members to determine the smallest rectangle that contains the graphic object. The 
graphic object's current world space transform and attribute bundle are used to determine the 
bounding rectangle. 

boundingRect 

Determines the smallest rectangle enclosing the graphic object. Graphic bundle 
attributes and the graphic object's current world transform matrix are used to 
determine the bounding rectangle. 

virtual IRectangle Supported On: 

boundingRect( I Graph i cContext& graphi cContext); PM 


Drawing 

Use these members to render a graphic object on a device. Derived classes must override 
drawOn. 


Provides the necessary drawing instructions for rendering the graphic object. This is 
a pure virtual function that must be overridden by all classes derived from IGraphic. 

virtual IGraphic& Supported On: 

drawOn ( IGraphi cContext& graphi cContext) = 0; PM 


Graphic Bundles 

Use these members to query, set, and remove the drawing attributes that you use when drawing 
the graphic object. 

graphicBundle 

Returns a copy of the graphic bundle currently set for this graphic object. If you do 
not set a graphic bundle for the graphic object, a graphic bundle with no attributes is 
returned. 
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virtual IGraphicBundle Supported On: 

graphicBundle() const; PM 

hasGraphicBundle 

Returns true if you set a graphic bundle on this graphic object. 

virtual IBase::Boolean 
hasGraphicBundle() const; 

removeGraphicBundle 

Removes the current graphic bundle. When you draw this graphic object, the 
attributes set in the graphic context are used instead of the attributes that were set in 
the graphic bundle. 

virtual IGraphic& 

removeGraphicBundle(); 

setGraphicBundle 

Makes a copy of the argument graphic bundle. The attributes you set in the bundle 
are used when you draw the graphic object. If this graphic object already has a 
graphic bundle set, the previous graphic bundle is deleted. 

virtual IGraphic& Supported On: 

setGraphicBundle( const IGraphicBundle& graphicBundl e); PM 


Supported On: 

PM 


Supported On: 

PM 


Hit Testing 

Hit testing is the process of determining which graphic objects, if any, intersect an area of 
interest. When you want to select an area of interest on the screen, you usually move the pointer 
to the area of interest and signal (by clicking the mouse, for example) that this is the graphic 
object you want. The area of interest is a small rectangle centered at the hit point whose size is 
determined by the hit aperture size. 

Use the contains member to determine if a point lies on or within the graphic object. 

Use the remaining members when you are performing hit testing using the hit-testing members 
provided by the IGList class. When an object is determined to be under a point, its 
setHitSelected member is called with a true argument. Typically, you do not need to set or 
check the hit selection state of a graphic object because the IGList class returns the graphic 
objects under the specified point. You can, however, control whether you want a graphic object 
contained in an IGList to be selectable by calling setSelectable with a false argument. In this 
case, this graphic object is not considered when hit testing is performed. 
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Returns true if the point lies on or within the object. This function uses drawOn( 
IGraphicContext& ) to determine if the object contains the point. 


virtual IBase::Boolean 
contains( I GraphicContext& graphicContext, 
const IPoint& point); 


Supported On: 

PM 


isHitSelectable 

Returns true if you want the graphic object to be selectable when hit testing is 
performed on an IGList. 


virtual IBase: :Boolean Supported On: 

isHitSelectable() const; PM 

_Return trues if setHitSelected was set to true and if isHitSelectable is true. 


virtual IBase::Boolean 
isHitSelected() const; 


Supported On: 

PM 


setHitSelectable 

Indicate whether this graphic object is selectable. This is useful when performing hit 
testing. Set setSelectable to false for all objects that you do not want or need to be 
selected. The default is true. If you set setSelected to false, the IGList class does not 
attempt to determine if a point lies within this graphic object. 

virtual IGraphic& Supported On: 

setHitSelectable( IBase: :Boolean hitSelectable = true); PM 

setHitSelected 

Indicates that this graphic object is selected The default is false. This function is 
used by the IGList class to mark the graphic objects that have been selected. Before 
performing hit testing using the functions provided in IGList, each graphic objects hit 
selection state is reset to false. 

virtual IGraphic& Supported On: 

setHitSelected( IBase:: Bool ean hitSelected = false); PM 


Object Identifier 

Use these members to associate an identifier with a graphic object. This is particularly useful 
when this object is part of an IGList (or any other collection) and you want to retrieve it later. 
By default, all object identifiers are zero. 
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Returns the graphic object's identifier. 


virtual unsigned long Supported On: 

id() const; PM 

..Sets the graphic object's identifier. 


virtual IGraphic& 

set I d ( unsigned long identifier); 


Supported On: 

PM 


Protected Constructors 

You cannot construct, destruct, or copy an object of this class directly. 


IGraphic 


virtual 

"IGraphicO; 


Supported On: 

PM 


World Space Transformation 

A transformation is an operation performed on a graphic object that changes the object in one of 
four ways: translation, rotation, scaling, and shearing. Transformations enable an application to 
control the location, orientation, size, and shape of graphic objects on an output device. 

The transformation of graphic objects can be conceptually divided into a series of distinct 
transformations applied from one logical stopping point to another. Coordinate spaces are used 
as a method of conceptualizing these logical stopping points. The coordinate spaces are concepts 
used to explain and manipulate the transformation process. 

The world coordinate space is where most drawing coordinates are specified. If you picture the 
presentation space as a blank canvas on which to draw, the world coordinate space is a Cartesian 
grid that provides a reference scale for what is being drawn. 

The components of a picture defined in world coordinate space are often defined to a scale 
convenient to only that component. Applications also can define each component, or subpicture , 
starting at the origin (0,0). This enables applications to define the scale of a subpicture and the 
location of the subpicture separately. 

After subpictures are defined in world coordinate space, they undergo a process called 
transformation and then appear on an output device. If an application has not specifically applied 
a transformation on a subpicture, by default the identity transform is applied, which, in effect, 
makes no change to the subpicture. 
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Both the OS/2 operating system and Windows provide multiple coordinate spaces and use 
transformations to move subpictures between the coordinate spaces. The transformations you 
apply to a graphic object transform an object's data points from one coordinate space to another. 
In the OS/2 operating system, the graphic object's transform matrix is used to map from world 
coordinate space to model coordinate space. In Windows, the graphic object's transform matrix 
is used to map from world coordinate space to page coordinate space. 

The transformation matrix does not affect an object's data points. The matrix is used to map the 
object's data points from world coordinate space when you draw the graphic object or perform hit 
testing on the graphic object. 

When you draw a graphic object, the object's transform matrix is applied to the graphic context's 
current world transform matrix using the transform method. 

By default, an object's transform matrix replaces the graphic context's current transform matrix 
before drawing and restores the previous transform matrix after drawing. You can provide an 
accumulative effect on transform matrixes by using the leftMultiply or rightMultiply transform 
method. 

The leftMultiply transform method premultiplies the graphic object's transform matrix with the 
graphic context's world transform matrix before drawing the graphic object. 

The rightMultiply transform method postmultiplies the graphic object's transform matrix with the 
graphic context's world transform matrix before drawing the graphic object. 

hasT ransform Matrix 

Returns true if the graphic object's transform matrix is not the identity transform 
matrix. 

virtual IBase::Boolean 
hasTransformMatrix() const; 

resetT ransformMatrix 

Sets the graphic object's transform matrix to the identity transform matrix. 

virtual IGraphic& Supported On: 

resetTransformMatrix(); PM 

-Rotates the object by the angle, specified in degrees, around the point specified. 

virtual IGraphic& Supported On: 

rotateBy( double angle, PM 

const IPoint& point = IPoint (0,0)); 


Supported On: 

PM 
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Exceptions 

IAccessError 


The system could not perform the rotate operation. Make sure the object is 
not being accessed concurrently on another thread. 


-Scales the object using the x and y factors around the point specified. 


virtual IGraphic& Supported On: 

scaleBy( double xScale, PM 

double yScale, 

const IPoint& point = IPoint (0,0)); 


Exceptions 

IAccessError The system could not perform the scale operation. Make sure the object is 

not being accessed concurrently on another thread. 


setTransform Matrix 

Replaces the graphic object's transform matrix with the argument transform matrix. A 
copy of the argument transform matrix is created and the previous transform matrix is 
deleted. 


virtual IGraphic& Supported On: 

setTransformMatrix( PM 

const ITransformMatrix& transformMatrix); 

setTra nsf o rm Met h od 

Sets the method used to combine the graphic object's transform matrix with the 
existing graphic context world transform matrix. 


virtual IGraphic& 
setTransformMethod( 

TransformMethod transformMethod = rightMultiply); 


Supported On: 

PM 


transformMatrix 

This function returns the graphic object's transform matrix. If no transformations 
operations have been called, then the identity matrix is returned. 


const ITransformMatrix Supported On: 

transformMatrix() const; PM 

transformMethod 

Returns the method used to combine world transform matrixes. 


© IBM Corp. 1992, 1995 


IGraphic 693 





IGraphic 


IGraphic: :TransforinMethod Supported On: 

transformMethod() const; PM 

_Moves the object by the amount specified in the IPoint. 


virtual IGraphic& 
translateBy( const IPoint& point); 


Supported On: 

PM 


Exceptions 

IAccessError The system could not perform the translate operation. Make sure the 

object is not being accessed concurrently on another thread. 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Comparisons 

Use these members to compare two IGraphic objects. 

_ Returns true if the graphics are not identical (includes the graphic bundle and the 
transform matrix). 

I Base:: Boolean Supported On: 

operator ! = ( const IGraphic& graphic) const; PM 

_ Returns true if the graphics are identical (includes the graphic bundle and the 
transform matrix). 

I Base:: Boolean Supported On: 

operator ==( const IGraphic& graphic) const; PM 
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Protected Constructors 

You cannot construct, destruct, or copy an object of this class directly. 

IGraphic 

Q IGraphic(); Supported On: 

PM 

Use the default constructor when you want to create an IGraphic object that does not 
contain an attribute bundle and with its transformation matrix is initialized to the 
identity transform. 

§ IGraphic( const IGraphicBundl e& graphicBundle); Supported On: 

PM 

Use this function when you want to create a IGraphic object from an IGraphicBundle 
(p. 697) object. The IGraphic object make a copy of the argument IGraphicBundle 
object and initializes its transformation matrix to the identity transform. 

graphicBundle 

A IGraphicBundle object. The IGraphic object uses the attributes set in 
the graphic bundle when drawing. 

g IGraphic( const IGraphic& graphic); Supported On: 

PM 


Use this function when you want to create a IGraphic object from another IGraphic 
object. 

graphic Reference to another class derived from IGraphic. 

.Use this function when you want to assign a IGraphic object to another IGraphic 

object. 

IGraphi c& Supported On: 

operator =( const IGraphic& graphic); PM 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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TransformMethod 

TransformMethod { 
replace, 
ri ghtMul ti ply, 
1eftMultiply 
}; 
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IBase 

IGraphicBundle 


_.None. 
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The IGraphicBundle class allows you to set drawing attributes for graphic objects 
(such as IGLine, IGArc, and IGPolyline). There are cases where this class allows 
you to set an attribute for a graphic object that does not support the attribute. For 
example, you can set a fill color for a graphic bundle object. You then set the 
graphic bundle object on a IGLine object. The fill color has no effect when you draw 
the line because lines do not have fill colors. 

The graphic bundle class allows you to selectively change drawing attributes from the 
drawing attributes currently set for a graphic context. If a graphic object does not 
contain a graphic bundle, the current graphic context drawing attributes are used when 
you draw a graphic object. If you call a set attribute function of a graphic bundle 
object and set the graphic bundle on a graphic object, this graphic bundle's attributes 
override the drawing attributes for the graphic context when you draw the graphic 
object. For drawing attributes that you have not changed using a set attribute 
function, the current drawing attributes set in the graphic context are used when you 
draw a graphic object. 

Each drawing attribute has four functions associated with it: set, query, has, and reset. 
You use a set function to set a drawing attribute on the graphic bundle You use a 
query function to obtain a drawing attribute set on a graphic bundle. You use a has 
function to determine if a drawing attribute is set on a graphic object. And, there is a 
reset function to use the current graphic context drawing attribute. Thus, the drawing 
attribute set in the graphic bundle is no longer used when drawing a graphic object. 


Public Functions 
Background Mix Mode 

Use these members to govern how the background color of a graphic object is combined with 
any existing drawing. The background of an object is the area between fill lines when you draw 
a closed figure using a nonsolid fill pattern, the area of a character box when you draw a graphic 
string, or the 0 bits when you draw a 1-bit-per-pel bitmap. The default background mix mode is 
backLeaveAlone. This background mix mode has no effect on the background color when you 
draw a graphic object. The following is a list of the supported background mix modes. 

backLeaveAlone The resulting color is determined by the display surface. 

backOverPaint The resulting color is determined by the background color. 
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backOr The resulting color is determined by the bitwise OR of the background color 

and the color of the drawing surface. 

backXor The resulting color is determined by the bitwise XOR of the background color 

and the color of the drawing surface. 


backgroundMixMode 

Returns the background mix mode. If you have not set a background mix mode on 
the graphic bundle, the default background mix mode of the graphic context is 
returned. 

BackgroundMixMode 
backgroundMixMode() const; 

hasBackgroundMixMode 

Returns true if you have set the background mix mode on the graphic bundle. 

I Base:: Bool ean Supported On: 

hasBackgroundMixMode() const; PM 

resetBackgroundMixMode 

Does not use the background mix mode set in the graphic bundle when you draw 
graphic objects with this graphic bundle. The current graphic context background 
mix mode is used. 

IGraphicBundle& 
resetBackgroundMixMode(); 

set Backg rou nd M ixMode 

Sets the background mix mode. 

IGraphicBundl e& Supported On: 

setBackgroundMixMode( PM 

BackgroundMixMode backgroundMixMode = backLeaveAlone); 


Supported On: 

PM 


Supported On: 

PM 


Color Attributes 

Use these members to control the use of pen, fill, and background colors for a graphic bundle. 
The pen color specifies the color used when you draw lines or when you frame a closed figure. 
You use the fill color to specify the color of the interior of a closed figure, such as an ellipse. 

The background color is used when you draw a closed figure, a graphic string, or a 1-bit-per-pel 
bitmap. If you set the fill pattern to IGraphicBundle:Tilled, the background color does not have 
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an effect. If, however, you specify a fill pattern of IGraphicBundle::vertical, for example, the 
color between the vertical lines is the current background color. The default background mix 
mode is IGraphicBundle:ibackLeave Alone; it specifies that the background color is not drawn. 
This means that for a nonsolid fill pattern, the drawing surface color shows through. The 
background color for nonsolid fill patterns appears only if the background mix mode is changed 
to IGraphicBundle: :backOverPaint. 

When you draw a graphic string, you can use the background color to specify the color of the 
character box that each character is drawn in. 

When you draw a 1-bit-per-pel bitmap, the background color is used when drawing the bits that 
have a 0 value, whereas the pen color is used to draw the bits that have a 1 value. 


backgroundColor 

Returns the background color. If you have not set a background color, the default 
background color of the graphic context is returned. Unless you change it, the default 
is black. 


IColor Supported On: 

backgrounded or () const; PM 

Returns the fill color. If you have not set a fill color, the default fill color of the 
graphic context is returned. Unless you change it, the default is black. 

IColor Supported On: 

fi 11 Col or() const; PM 


hasBackgroundColor 

Returns true if you have set the background color on the graphic bundle. 


I Base:: Boolean Supported On: 

hasBackgroundColor() const; PM 

—Returns true if you have set the fill color on the graphic bundle. 


IBase::Boolean 
hasFi 11 Color() const; 

—Returns true if you have set the pen color on the graphic bundle. 


IBase::Boolean Supported On: 

hasPenColor() const; PM 


Supported On: 

PM 
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_ Returns the pen color. If you have not set pen color, the default pen color of the 
graphic context is returned. Unless you change it, the default is black. 

IColor 

penColor() const; 

resetBackgroundColor 

Does not use the background color set in the graphic bundle when you draw graphic 
objects with this graphic bundle. The current graphic context background color is 
used. 

IGraphi cBundl e& Supported On: 

resetBackgroundColor(); PM 


Supported On: 

PM 


resetFillColor 

Does not use the fill color set in the graphic bundle when you draw graphic objects 
with this graphic bundle. The current graphic context fill color is used. 

IGraphicBundle& 
resetFillColor(); 

resetPenColor 

Does not use the pen color set in the graphic bundle when you draw graphic objects 
with this graphic bundle. The current graphic context pen color is used. 

IGraphicBundl e& Supported On: 

resetPenColor(); PM 


Supported On: 

PM 


setBackgroundColor 

Sets the current background color. 


IGraphicBundle& Supported On: 

setBackgroundColor( const IColor& backColor); PM 

_Sets the current fill color. 


IGraphicBundle& Supported On: 

setFi 11 Col or( const IColor& fill Col or); PM 

_Sets the current pen color. 
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I GraphicBundle& 

setPenColor( const IColor& penColor); 


Supported On: 

PM 


Comparisons 

Use these members to compare two IGraphicBundle objects. 

_Returns true if the drawing attributes are not identical. 


I Base:: Boolean Supported On: 

operator ! = ( const IGraphicBundl e& graphicBundl e); PM 

Re turns true if all drawing attributes are identical 


I Base:: Boolean Supported On: 

operator ==( const IGraphicBundl e& graphi cBundl e); PM 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 

IGraphicBundle 

Q IGraphicBundle( const IGraphi cBundl e& graphi cBundl e); Supported On: 

PM 

Use this function to construct a IGraphicBundle object from another IGraphicBundle 
object. The drawing attributes set in the graphic bundle object are set in the new 
graphic bundle object. 

graphicBundle A IGraphicBundle object. 

Q IGraphicBundl e(); Supported On: 

PM 

Use the default construct to create an IGraphicBundle object. Initially, no drawing 
attributes are set. 

g IGraphicBundle( const IGraphicContext& graphicContext); Supported On: 

PM 

Use this function to construct a IGraphicBundle object from a IGraphicContext object. 
All drawing attributes in the graphic bundle object are set to the current graphic 
context drawing attributes. 
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graphicContext A IGraphicContext object. 


.Use this function to assign a IGraphicBundle object to another IGraphicBundle 

object. 

IGraphi cBundle& Supported On: 

operator =( const IGraphicBundl e& graphi cBundl e); PM 


"IGraphicBundle 

"IGraphicBundle(); 


Supported On: 

PM 


Draw Operations 

Use these members to control the method used to draw a closed graphic object (such as IGPie, 
IGChord, IGPolygon, IGRectangle, or IGEllipse). The draw operation's values are as follows: 

fill Only the interior of the graphic object is drawn, 

frame Only the frame of the graphic object is drawn. 

fillAndFrame The interior and the frame of the graphic object are drawn. 

drawOperation 

Returns the draw operation. If you have not set a draw operation, the default draw 
operation of the graphic context is returned. 

DrawOperation 
drawOperation() const; 

hasDrawOperation 

Returns true if you have set the draw operation on the graphic bundle. 

IBase::Boolean 
hasDrawOperation() const; 

resetDrawOperation 

Does not use the draw operation set in the graphic bundle when you draw graphic 
objects with this graphic bundle. The current graphic context draw operation is used. 

IGraphi cBundle& Supported On: 

resetDrawOperati on (); PM 


Supported On: 

PM 


Supported On: 

PM 
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setDrawOperation 

Sets the draw operation. This attribute only affects closed graphic objects. 


I GraphicBundle& 
setDrawOperation( 

DrawOperation drawOperation = fi11AndFrame); 


Supported On: 

PM 


Mix Mode 

Use these member to govern how the pen and fill colors of a graphic object are combined with 
any existing drawing. The default mix mode is overPaint. When you draw a graphic object with 
this mix mode, the pen and fill colors used to draw the graphic object paint over any existing 
drawing in the same area on the drawing surface. The following is a list of the supported mix 
modes. 


Note: The description of each mix mode refers to the pen color, but the same description 
applies to the fill color as well. 

or Resulting color is determined by a bitwise OR of the pen color and the 

drawing surface. 

overPaint Resulting color is determined by pen color. This is the default for the pen 

mix attribute. 


xor 


leaveAlone 

and 

subtract 

maskSourceNot 

black 

notMergeSource 

notXorSource 

invert 


Resulting color is determined by a bitwise XOR of the pen color and the 
drawing surface. This mode enables graphic objects to be drawn so that 
they can be removed easily by simply drawing them a second time using the 
xor mix mode. This is useful for graphic animation when an application 
must move a graphic object and completely restore the graphic objects that it 
originally overlapped. 

Resulting color is determined by the drawing surface. 

Resulting color is determined by a bitwise AND of the pen color and the 
drawing surface. 

Resulting color is determined by inverting the pen color and performing a 
bitwise AND with the drawing surface. 

Resulting color is determined by inverting the surface color and performing 
a bitwise AND with the pen color. 

Resulting color is black. 

Resulting color is the inverse of the or mix mode. 

Resulting color is the inverse of the xor mix mode. 

Resulting color is the inverse of the drawing surface. 
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mergeSourceNot 

notCopySource 

mergeNotSource 

notMaskSource 

white 


Resulting color is determined by a bitwise OR of the pen color and the 
inverse color of the drawing surface. 

Resulting color is the inverse of the pen color. 

Resulting color is determined by the inverse of the pen color and by 
performing a bitwise AND of the drawing surface. 

Resulting color is the inverse of the "and" pen mix. 

Resulting color is white. 


—Returns true if you have set the mix mode on the graphic bundle. 


IBase: :Boolean Supported On: 

hasMixMode() const; PM 

. Returns the mix mode. If you have not set a mix mode on the graphic bundle, the 
default mix mode of the graphic context is returned. 


MixMode 

mixMode() const; 


Supported On: 

PM 


resetMixMode 

Does not use the mix mode set in the graphic bundle when you draw graphic objects 
with this graphic bundle. The current graphic context mix mode is used. 


IGraphicBundle& Supported On: 

resetMixMode(); PM 

—Sets the mix mode. 


IGraphicBundle& 

setMixMode( MixMode mixMode = overPaint); 


Supported On: 

PM 


Pattern Origin 

Use these members to define a point from which the pen and fill patterns spread horizontally and 
vertically. The lower-left corner is aligned on this point and is expressed in world coordinate 
space. 

hasPatternOrigin 

Returns true if you have set the pattern origin point on the graphic bundle. 
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I Base:: Boolean Supported On: 

hasPatternOrigin() const; PM 

_ Returns the origin point of the pen and fill patterns. If the pattern origin has not 
been set on the graphic bundle, the default pattern origin point of the graphic context 
is returned. 

IPoint 

patternOrigin() const; 

resetPatternOrigin 

Does not use the pattern origin point set in the graphic bundle when you draw 
graphic objects with this graphic bundle. The current graphic context pattern origin 
point is used. 

IGraphicBundl e& Supported On: 

resetPatternOrigin(); PM 


Supported On: 

PM 


setPatternOrigin 

Sets the origin point to which the pen and fill patterns map. 

IGraphicBundl e& Supported On: 

setPatternOrigin( const IPoint& point = IPoint (0,0)); PM 


Pen and Fill Patterns 

Use these members to control the pattern used when you draw lines that have a pen width greater 
than 1 or when you fill a closed figure. 
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IGraphicBundleadensel 


IGraphicBundle:: dense? 
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I Graph i cBundle:: denser 


I Graph i cBundle:: dense6 
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IGraphicBundle::dense8 
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IGraph i cBundle: :hor i zontal 


IGraphicBundle::forewardDiag1 



“ □ 

IGraphicBundle::backwardDiag2 
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Figure 4. Pen and Fill Patterns 


.Returns the fill pattern. If you have not set a fill pattern on the graphic bundle, the 

default fill pattern of the graphic context is returned. 

unsigned long Supported On: 

fillPattern() const; PM 


hasFillPattern 

Returns true if you have set the fill pattern on the graphic bundle. 

I Base:: Bool ean Supported On: 

hasFi 11 Pattern () const; PM 


hasPenPattern 

Returns true if you have set the pen pattern on the graphic bundle. 


IBase::Boolean 
hasPenPattern() const; 


Supported On: 

PM 
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—Returns the pen pattern. If you have not set a pen pattern on the graphic bundle, 
the default pen pattern of the graphic context is returned. 

unsigned long Supported On: 

penPattern() const; PM 


resetFillPattern 

Does not use the fill pattern set in the graphic bundle when you draw graphic objects 
with this graphic bundle. The current graphic context fill pattern is used. 

IGraphi cBundl e& Supported On: 

resetFi 11 Pattern(); PM 


resetPenPattern 

Does not use the pen pattern set in the graphic bundle when you draw graphic objects 
with this graphic bundle. The current graphic context pen pattern is used. 

IGraphicBundl e& Supported On: 

resetPenPattern (); PM 

— Sets the pattern used to fill a closed figure. You can also specify a bitmap handle 
that is used to fill a closed figure. The bitmap must be 8-by-8 and 1-bit-per-pel. 

IGraphicBundl e& Supported On: 

setFi 11 Pattern ( unsigned long fill Pattern = filled); PM 


setPenPattern 

Sets the pattern used for the pen. The pen width must be greater than 1 for the pen 
pattern to have an effect. 

IGraphi cBundl e& Supported On: 

setPenPattern( unsigned long penPattern = filled); PM 

Pen Type 

Use these members to define the way lines, arcs, polylines, and the frame on closed figures are 
drawn. The pen type can be solid, a series of dashes, a series of dots, or a combination of 
dashes and dots. If the pen width is greater than 1, graphic objects are drawn using a pen type 
of solid, regardless of the pen type set. The following is a list of the supported pen types: 

solid An uninterrupted line is drawn. This is the default pen type. 

dot A series of dots are drawn. 
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shortDash 

dashDot 

longDash 

dashDoubleDot 

alternate 

invisible 


A series of short dashes are drawn. 

A series of dash followed by a dot is drawn. 

A series of long dashes are drawn. 

A series of a dash followed by two dots are drawn. 
Alternate pels are drawn. 

The pen is not visible. 


IGraphicBundle Pen Types 


□ 


I Graph i cBundle:: soli d 


IGraphicBundle::dot 


IGraphicBundle:: shortDash 


IGraphicBundle:: dashDot 


IGraphicBundle::doubleDot 


-IGraphicBundle::longDash 


IGraphicBundle:: dashDoubleDot 


IGraphicBundle: alternate 


IGraphicBundle:: invisible 


Figure 5. Pen Types 


-.Returns true if you have set the pen type on the graphic bundle. 


IBase: :Boolean Supported On: 

hasPenType() const; PM 

.Returns the pen type. If you have not set the pen on the graphic bundle, the default 

pen type of the graphic context is returned. 


PenType Supported On: 

penTypeQ const; PM 
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resetPenType 

Does not use the pen type set in the graphic bundle when you draw graphic objects 
with this graphic bundle. The current graphic context pen type is used. 

IGraphicBundl e& Supported On: 

resetPenType(); PM 

_Sets the current pen type. The pen width must be 1 for a pen type other than solid 
to be used. 


I GraphicBundle& 

setPenType( PenType penType = solid); 


Supported On: 

PM 


Pen Width 

Use these members to govern the width of the pen when you draw lines or the width of the 
frame when you draw a closed figure. The width specified is in world coordinate space and is 
subject to world space transforms. If you specify a pen width greater than 1, the pen type is 
always solid. 

_ Returns true if you set the pen width on the graphic bundle. 

I Base:: Boolean Supported On: 

hasPenWidth() const; PM 

_ Returns the pen width. If you have not set the pen width on the graphic bundle, the 
default pen width of the graphic context is returned. 


unsigned long 
penWidth() const; 


Supported On: 

PM 


resetPenWidth 

Does not use the pen width set in the graphic bundle when you draw graphic objects 
with this graphic bundle. The current graphic context pen width is used. 

IGraphicBundl e& Supported On: 

resetPenWidth(); PM 

..Sets the width of the pen. If the value is greater than 1, the pen type is always 

solid. 

IGraphicBundl e& Supported On: 

setPenWidth( unsigned long lineWidth = 1); PM 
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Pen-Ending Style 

Use these members to control the shape of the unattached end of a line. The pen width must be 
greater than 1 for the pen-ending style to have an effect. The following is a list of the supported 
pen-ending styles: 

flat Lines drawn with this style are flat, finishing flush with the end points of the 

line. 

square Lines drawn with this style are flat, finishing past the end of the line. The line 

is extended by a distance that is equal to half the pen width. 

round Lines drawn with this style are rounded, finishing past the end of the line. The 

rounded end is constructed by drawing a circle whose radius is half the pen 
width. 



Flat Line-End Square Line-End Round Line-End 

Figure 6. Pen-Ending Styles 


hasPenEndingStyle 

Returns true if you have set the pen-ending style on the graphic bundle. 

I Base:: Bool ean Supported On: 

hasPenEndingStyle() const; PM 


penEndingStyle 

Returns the pen-ending style. If you have not set the pen-ending style on the graphic 
bundle, the default pen-ending style of the graphic context is returned. 

PenEndingStyle 
penEndingStyle() const; 

resetPenEndingStyle 

Does not use the pen-ending style set in the graphic bundle when you draw graphic 
objects with this graphic bundle. The current graphic context pen-ending style is 
used. 

IGraphi cBundl e& Supported On: 

resetPenEndingStyle(); PM 


Supported On: 

PM 
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setPenEndingStyle 

Sets the pen-ending style. The pen width must be greater than 1 for the pen-ending 
style to have an effect. 

IGraphicBundl e& Supported On: 

setPenEndingStyle( PenEndingStyle penEndingStyle = flat); PM 


Pen-Joining Style 

Use these members to control the shaped formed by two intersecting lines. The pen width must 
be greater than 1 for the pen-joining style to have an effect. The following is a list of the 
supported pen-joining styles: 

bevel The joint has a diagonal corner, 

round The joint has a rounded corner, 

miter The joint has a 90-degree-angled corner. 



Figure 7 . Pen-Joining Styles 


hasPenJoiningStyle 

Returns true if you have set the pen-joining style on the graphic bundle. 

I Base:: Boolean Supported On: 

hasPenJoiningStyle() const; PM 


penJoiningStyle 

Returns the pen-joining style. If you have not set the pen-joining style on the graphic 
bundle, the default pen joining style of the graphic context is returned. 
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PenJoi ni ngStyl e Supported On: 

penJoiningStyle() const; PM 

resetPenJoiningStyle 

Does not use the pen-joining style set in the graphic bundle when you draw graphic 
objects with this graphic bundle. The current graphic context pen-joining style is 
used. 

IGraphicBundle& 
resetPenJoiningStyle(); 

setPenJoiningStyle 

Sets the pen-joining style. The pen width must be greater than 1 for the pen-joining 
style to have an effect. 

IGraphicBundle& Supported On: 

setPenJoini ngStyl e( PenJoi ni ngStyl e penJoi ni ngStyl e = bevel); PM 


Supported On: 

PM 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 

Pen and Fill Patterns 

Use these members to control the pattern used when you draw lines that have a pen width greater 
than 1 or when you fill a closed figure. 

backwardDiagl 

Pattern used when you draw a line that have a width greater than 1 or when you fill a 
figure. 

static const unsigned long Supported On: 

backwardDiagl; PM 
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backward Diag2 


Pattern used when you draw a line that have a width greater than 1 or when you fill a 
figure. 


static const unsigned long 
backwardDiag2; 


Supported On: 

PM 


.. Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 


static const unsigned long 
densel; 


Supported On: 

PM 


..Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 


static const unsigned long 
dense2; 


Supported On: 

PM 


.. Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 


static const unsigned long 
dense3; 


Supported On: 

PM 


.. Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 


static const unsigned long 
dense4; 


Supported On: 

PM 


.. Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 


static const unsigned long 
dense5; 


Supported On: 

PM 


..Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 


static const unsigned long 
dense6; 


Supported On: 

PM 


-Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 
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filled 


forewardDiagl 


forewardDiag2 


static const unsigned long 
dense7; 

Pattern used when you draw a line that have a width greater than 
a figure. 


static const unsigned long 
dense8; 


static const unsigned long 
filled; 


Pattern used when you draw a line that have a width greater than 1 
figure. 

static const unsigned long 
forewardDiagl; 


Pattern used when you draw a line that have a width greater than 1 
figure. **** Create figure to illustrate patterns **** 

static const unsigned long 
forewardDiag2; 

Pattern used when you draw a line that have a width greater than 
a figure. 

static const unsigned long 
halftone; 

Pattern used when you draw a line that have a width greater than 
a figure. 

static const unsigned long 
hatched; 

—Pattern used when you draw a line that have a width greater than 
a figure. 


Supported On: 

PM 

1 or when you fill 


Supported On: 

PM 


Supported On: 

PM 


or when you fill a 


Supported On: 

PM 


or when you fill a 


Supported On: 

PM 

1 or when you fill 


Supported On: 

PM 

1 or when you fill 


Supported On: 

PM 

1 or when you fill 
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static const unsigned long Supported On: 

hatchedDiag; PM 

Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 

static const unsigned long Supported On: 

hollow; PM 

.Pattern used when you draw a line that have a width greater than 1 or when you fill 

a figure. 


static const unsigned long Supported On: 

horizontal; PM 

Pattern used when you draw a line that have a width greater than 1 or when you fill 
a figure. 


static const unsigned long 
vertical; 

Supported On: 

PM 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 



DrawOperation 

DrawOperation { 

fill. 


frame, 

fillAndFrame 


p. These functions control the method used to draw a closed graphic object (such as 
IGPie, IGChord, IGPolygon, IGRectangle, or IGEllipse). The draw operation's values 
are; 

fill Only the interior of the graphic object is drawn, 

frame Only the frame of the graphic object is drawn. 

fillAndFrame The interior and the frame of the graphic object are drawn. 


716 


Open Class Library Reference 



IGraphicBundle 


BackgroundMixMode 

BackgroundMixMode { 
backLeaveAl one, 
backOverPaint, 
backOr, 
backXor 
}; 


These functions govern how the background color of a graphic object is combined 
with any existing drawing. The background of an object is the area between fill lines 
when you draw a closed figure using a nonsolid fill pattern, the area of a character 
box when you draw a graphic string, or the 0 bits when you draw a 1-bit-per-pel 
bitmap. The default background mix mode is backLeaveAlone. This background 
mix mode has no effect on the background color when you draw a graphic object. 

The following is a list of the supported background mix modes. 


backLeaveAlone 

backOverPaint 

backOr 

backXor 


The resulting color is determined by the display surface. 

The resulting color is determined by the background color. 
The resulting color is determined by the bitwise OR of the 
background color and the color of the drawing surface. 

The resulting color is determined by the bitwise XOR of the 
background color and the color of the drawing surface. 


PenEndingStyle 


PenEndingStyle { 
flat, 
square, 
rounded 
1 ; 


These functions control the shape of the unattached end of a line. The pen width 
must be greater than 1 for the pen-ending style to have an effect. The following is a 
list of the supported pen-ending styles. 

flat Lines drawn with this style are flat, finishing flush with the end 

points of the line. 

square Lines drawn with this style are flat, finishing past the end of the 

line. The line is extended by a distance that is equal to half the 
pen width. 

round Lines drawn with this style are rounded, finishing past the end of 

the line. The rounded end is constructed by drawing a circle whose 
radius is half the pen width. 
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MixMode { 

or, overPaint, xor, leaveAlone, and, 

subtract, maskSourceNot, black, notMergeSource, notXorSource, 

invert, mergeSourceNot, notCopySource, mergeNotSource, notMaskSource, 

whi te 

}; 

The functions govern how the pen and fill colors of a graphic object are combined 
with any existing drawing. The default mix mode is overPaint. When you draw a 
graphic object with this mix mode, the pen and fill colors used to draw the graphic 
object paints over any existing drawing in the same area on the drawing surface. The 
following is a list of the supported mix modes. 

Note: The description of each mix mode refers to the pen color, but the same 
description applies to the fill color as well. 

or Resulting color is determined by a bitwise OR of the pen color and 

the drawing surface. 

overPaint Resulting color is determined by pen color. This is the default for 

the pen mix attribute. 

xor Resulting color is determined by a bitwise XOR of the pen color 

and the drawing surface. This mode enables graphic objects to be 
drawn so that they can be removed easily by simply drawing them 
a second time using the xor mix mode. This is useful for graphic 
animation when an application must move a graphic object and 
completely restore the graphic objects that it originally overlapped. 

leaveAlone Resulting color is determined by the drawing surface. 

and Resulting color is determined by a bitwise AND of the pen color 

and the drawing surface. 

subtract Resulting color is determined by inverting the pen color and 

performing a bitwise AND with the drawing surface. 

maskSourceNot Resulting color is determined by inverting the surface color and 
performing a bitwise AND with the pen color. 

black Resulting color is black. 

notMergeSource Resulting color is the inverse of the or mix mode. 

notXorSource Resulting color is the inverse of the xor mix mode. 

invert Resulting color is the inverse of the drawing surface. 

mergeSourceNot Resulting color is determined by a bitwise OR of the pen color and 

the inverse color of the drawing surface. 
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notCopySource 

mergeNotSource 

notMaskSource 

white 


Resulting color is the inverse of the pen color. 

Resulting color is the determined by the inverse of the pen color 
and performing a bitwise AND of the drawing surface. 

Resulting color is the inverse of the and pen mix. 

Resulting color is white. 


PenType { 

solid, dot, shortDash, dashDot, doubleDot, 

longDash, dashDoubleDot, alternate, invisible 

}; 


These functions define the way lines, arcs, polylines, and the frame on closed figures 
are drawn. The pen type can be solid, a series of dashes, a series of dots, or a 
combination of dashes and dots. If the pen width is greater than 1, graphic objects 
are drawn using a pen type of solid regardless of the pen type set. The following is a 
list of the supported pen types. 


solid 

dot 

shortDash 

dashDot 

longDash 

dashDoubleDot 

alternate 

invisible 


An uninterrupted line is drawn. This is the default pen type. 
A series of dots are drawn. 

A series of short dashes are drawn. 

A series of dash followed by a dot is drawn. 

A series of long dashes are drawn. 

A series of a dash followed by two dots are drawn. 

Alternate pels are drawn. 

The pen is not visible. 


PenJoiningStyle 

PenJoiningStyle { 
bevel, 
round, 
mi ter 
}; 


These functions control the shaped formed by two intersecting lines. The pen width 
must be greater than 1 for the pen-joining style to have an affect. The following is a 
list of the supported pen-joining styles. 

bevel The joint has a diagonal corner. 

round The joint has a rounded corner. 

miter The joint has a 90 degree angled corner. 
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IBase 

IVBase 

IGraphicContext 


_.None. 
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The IGraphicContext class is used to render graphic objects on a device. 
IGraphicContext contains the graphic state information used when drawing graphics. 
The graphic state includes the current attribute bundle, the current world space 
transform matrix, and the current clip region. 

If you are familiar with the use of presentation spaces in Presentation Manager or 
device contexts in Windows, you can view IGraphicContext as a wrapper class for 
these data types. 

The IGraphicContext class also contains a static collection of default drawing 
attributes that initialize the attributes of the graphic context when you create it. You 
can change any of these default drawing attribute so that any graphic context created 
subsequently will be initialized with these new drawing attributes. 

You can at any time use other native graphic programming interfaces whose function 
has not been included in either this class or any of the IGraphic subclasses. You can 
do this by accessing either the presentation space handle or device context by using 
the handle member function as the first parameter to the graphic programming 
interface. 


Public Functions 
Boundary Accumulation 

Use these members to query a bounding rectangle of one or more graphic objects. Normally, 
you do not need to use these function. Instead, use IGraphic::boundingRect to query the 
bounding rectangle of a graphic object. 

startBoundaryAccumulation 

Starts the boundary accumulation process, subsequent drawing operations are added to 
the bounding rectangle. Drawing operations are not visible when you are 
accumulating boundary data. 

virtual IGraphicContext& Supported On: 

startBoundaryAccumul ation (); PM 
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Exceptions 

IAccessError An error occurred while attempting to start boundary accumulation. Refer 

to the exception text for specific error information. 


stopBoundaryAccumulation 

Stops the boundary accumulation process and returns the bounding rectangle of all 
drawing operations that were made since calling the startBoundaryAccumulation 
function. Subsequent draw functions are visible. 


virtual IRectangle 
stopBoundaryAccumulation(); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to stop boundary accumulation. Refer 

to the exception text for specific error information. 


Constructors 

You can construct and destruct objects of this class. 

IGraphicContext 

Q IGraphicContext( const ISize& contextSize) ; Supported On: 

PM 

Use this function to create a IGraphicContext object from a ISize object. This creates 
a memory graphic context and sets a bitmap into the graphic context with the 
dimensions specified in the ISize object. This allows you to draw into a bitmap. 

When you are finished drawing, you can create a IGBitmap object from the graphic 
context using the IGBitmap constructor which takes a IGraphicContext object and an 
IRectangle object as parameters. 

| IGraphicContext (); Supported On: 

PM 

Use the default constructor to create a graphic context. This creates a memory 
graphic context. A memory graphic context is used when you want to draw graphic 
objects in memory and subsequently create a bitmap from the drawn graphic objects. 

0 IGraphicContext( const IPresSpaceHandle& presSpaceHandle) ; Supported On: 

PM 
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Use this member to construct a IGraphicContext object from an IPresSpaceHandle 
object. You would typically use this member to construct a IGraphicContext object 
from the IPresSpaceHandle object provided during paint events. 

Note: If you construct a IGraphicContext object with this constructor, the 

IPresSpaceHandle is not be destroyed when the IGraphicContext is deleted. 

presSpaceHandle Handle of presentation space. 


0 IGraphicContext( const IWindowHandle& windowHandle); Supported On: 

PM 

Use this function to create a IGraphicContext object from a IWindowHandle object. 

A graphic context is created that is compatible with the screen device that is 
associated with the window handle. 

windowHandle Window handle used to get a presentation space in OS/2 (or 
device context in Windows). 


IGraphicContext 


virtual 

"IGraphicContextO; 


Supported On: 

PM 


Conversions 

Use these member to use the graphic context with native programming interfaces. 

Returns the presentation space handle wrappered by the graphic context. 

IPresSpaceHandle Supported On: 

handle() const; PM 


Current Drawing Position 

Use these members to set and query the graphic context's current drawing position. These 
functions are useful when you are creating your own graphic object derived from IGraphic. 

currentDrawingPosition 

Returns the graphic context's current drawing position. 

virtual IPoint Supported On: 

currentDrawingPosition() const; PM 
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setCurrentDrawing Position 

Sets the graphic context's current drawing position to the point specified. 


virtual IGraphicContext& 
setCurrentDrawingPosition( const IPoint& point); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the current drawing position. 

Refer to the exception text for specific error information. 


Default Drawing Attributes 

Use these members to set and query the default drawing attributes that are used to initialize the 
drawing attributes of a graphic context when a graphic context is created. 

defaultBackgroundColor 

Returns the default background color. Unless you change it, the default background 
color is black. 

static IColor Supported On: 

defaul tBackgroundColor(); PM 

defaultBackgroundMixMode 

Returns the default background mix mode. Unless you change it, the default 
background mix mode is IGraphicBundle::backLeaveAlone. 

static IGraphicBundle::BackgroundMixMode 
defaultBackgroundMixMode(); 

defaultDrawOperation 

Returns the default drawing operation. Unless you change it, the default draw 
operation is IGraphicBundle::fillAndFrame. 

static IGraphicBundle: :DrawOperation Supported On: 

defaul tDrawOperation(); PM 


Supported On: 

PM 


defaultFillColor 

Returns the default fill color. Unless you change it, the default fill color is black. 

static IColor Supported On: 

defaul tFi 11 Col or(); PM 
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defaultFillPattern 

Returns the default fill pattern. Unless you change it, the default fill pattern is 
IGraphicBundle:: solid. 

static unsigned long Supported On: 

defaul t Fi 11 Pattern (); PM 


defaultMixMode 

Returns the default mix mode. Unless you change it, the default mix mode is 
IGraphicBundle: :overPaint. 

static IGraphicBundle::MixMode 
defaultMixMode(); 

defaultPatternOrigin 

Returns the default pattern origin point. Unless you change it, the default pattern 
origin is 0,0. 

static IPoint Supported On: 

defaultPatternOrigin(); PM 


Supported On: 

PM 


defaultPenColor 

Returns the default pen color. Unless you change it, the default pen color is black. 

static IColor Supported On: 

defaul tPenColor(); PM 

defaultPenEndingStyle 

Returns the default pen-ending style. Unless you change it, the default pen-ending 
style is IGraphicBundle: :flat. 

static IGraphicBundle::PenEndingStyle 
defaultPenEndingStyle(); 

defaultPenJoiningStyle 

Returns the default pen-joining style. Unless you change it, the default pen-joining 
style is IGraphicBundle::bevel. 

static IGraphicBundle::PenJoiningStyle Supported On: 

defaul tPenJoi ningStyl e(); PM 


Supported On: 

PM 
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defaultPenPattern 

Returns the default pen pattern. Unless you change it, the default pen pattern is 
IGraphicBundle::solid. 

static unsigned long Supported On: 

defaul tPenPattern(); PM 


defaultPenType 

Returns the default pen type. Unless you change it, the default pen type is 
IGraphicBundle::solid. 

static IGraphicBundle: :PenType Supported On: 

defaul tPenType(); PM 


defaultPenWidth 

Returns the default pen width. Unless you change it, the default pen width is 1. 

static unsigned long Supported On: 

defaul tPenWidth (); PM 

setDefaultBackgroundColor 

Sets the default background color. 

static void Supported On: 

setDefaul tBackgroundCol or( const IColor& backgroundCol or); PM 


setDefaultBackgroundMixMode 

Sets the default background mix mode. 


static void Supported On: 

setDefaultBackgroundMixMode( PM 

IGraphicBundle::BackgroundsxMode backMixMode); 

setDefaultDrawOperation 

Sets the default draw operation. 


static void 

setDefaul tDrawOperation ( 

IGraphicBundle::DrawOperation drawOperation); 


Supported On: 

PM 
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setDefaultFillColor 

Sets the default fill color. 

static void 

setDefaultFi 11 Col or( const IColor& fill Col or); 

setDefaultFillPattern 

Sets the default fill pattern. 

static void 

setDefaultFi11 Pattern( unsigned long fi11 Pattern); 

setDefaultMixMode 

Sets the default mix mode for the pen and fill operations, 
static void 

setDefaultMixMode( IGraphicBundle::MixMode mixMode); 

setDefaultPatternOrigin 

Sets the default pattern origin point. 

static void 

setDefaultPatternOrigin( const IPoint& point); 

setDefaultPenColor 

Sets the default pen color. 

static void 

setDefaultPenColor( const IColor& penColor); 

setDefaultPenEndingStyle 

Sets the default pen-ending style. The pen width must be greater than 
pen-ending style to have an effect. 

static void 

setDefaultPenEndingStyle( 

IGraphicBundle::PenEndingStyle penEndingStyle); 

setDefaultPenJoiningStyle 

Sets the default pen-joining style. The pen width must be greater than 
pen-joining style to have an affect. 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


1 for the 


Supported On: 

PM 


1 for the 
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static void Supported On: 

setDefaul tPenJoini ngStyl e( PM 

IGraphicBundle::PenJoiningStyle penJoiningStyle); 

setDefaultPenPattern 

Sets the default pen pattern. 


static void Supported On: 

setDefaultPenPattern( unsigned long penPattern); PM 

setDefaultPenType 

Sets the default pen type. The pen width must be 1 to use a nonsolid pen type. 


static void Supported On: 

setDefaul tPenType( IGraphi cBundl e:: PenType penType); PM 

setDefaultPenWidth 

Sets the default pen width. 


static void 

setDefaultPenWidth( unsigned long penWidth); 


Supported On: 

PM 


Device Space Transformation 

The device space is the coordinate space in which a picture is drawn before it appears in a 
display screen window or on the printer or plotter. 

The device space is defined in device-specific units. Depending upon the mapping mode used, 
device coordinate units can be pels, increments of an inch, increments of a meter, or they can be 
arbitrary. 

The device transformation is defined by two rectangles. The first rectangle is called the 
"presentation page" in the OS/2 operating system and the "window extent" in Windows. The 
second is called the "page viewport" in the OS/2 operating system and the "viewport extent" in 
Windows. The device transformation is established when the graphic context is created or 
resized. 

With the exception of the isotropic mapping mode, the page size and view port rectangle are 
fixed and are, therefore, predetermined. If you attempt to set the page size or viewport rectangle 
when the graphic context's mapping mode is not isotropic, the operations are ignored. 

_ Returns the page size of the graphic context. 
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virtual ISize Supported On: 

pageSize() const; PM 

IPM This function is equivalent to querying the presentation page size using GpiQueryPS. 

— Sets the page size of the graphic context. This function is ignored if the graphic 
context's mapping mode is not isotropic. 

virtual IGraphicContext& Supported On: 

setPageSize( const ISize& pageSize); PM 

IPM The function is equivalent to setting the page size when using GpiCreatePS or 
GpiSetPS. 

setViewPortRect 

Sets the viewport rectangle of the graphic context. This function is ignored if the 
graphic context's mapping mode is not isotropic. 


IPM 


virtual IGraphicContext& Supported On: 

setViewPortRect( const IRectangle& viewportRectangle); PM 

This function is equivalent to setting the page viewport rectangle using 
GpiSetPageViewport. 


—Returns the viewport rectangle. 


IPM 


virtual IRectangle 
viewPortRect() const; 

This function is equivalent to querying the page viewport using 
GpiQueryPageViewport. 


Supported On: 

PM 


Drawing 

Use these members to render the graphic objects on the device associated with the graphic 
context. Typically, you use the graphic object's drawOn member to render a graphic object. 
These functions are provided in this class to consolidate the native drawing operations. 


draw 


Q 


virtual IGraphicContext& 
draw( const IGPie& pie); 


Supported On: 

PM 
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Exceptions 

IAccessError An error occurred while attempting to draw the graphic object. Refer to 

the exception text for specific error information. 


2 virtual IGraphicContext& 

draw( const IGLine& line); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to draw the graphic object. Refer to 

the exception text for specific error information. 


0 virtual IGraphicContext& Supported On: 

draw( const IGPolyline& polyline); PM 


Exceptions 

IAccessError An error occurred while attempting to draw the graphic object. Refer to 

the exception text for specific error information. 


0 virtual IGraphicContext& Supported On: 

draw( const IGPolygon& polygon); PM 


Exceptions 

IAccessError An error occurred while attempting to draw the graphic object. Refer to 

the exception text for specific error information. 


g virtual IGraphicContext& Supported On: 

draw( const IGE11 ipse& geometry); PM 


Exceptions 

IAccessError An error occurred while attempting to draw the graphic object. Refer to 

the exception text for specific error information. 


E virtual IGraphicContext& Supported On: 

draw( const IGRectangle& graphi cRectangl e); PM 


Exceptions 

IAccessError An error occurred while attempting to draw the graphic object. Refer to 

the exception text for specific error information. 
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Q virtual IGraphicContext& 
draw( const IGArc& arc); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to draw the graphic object. Refer to 
the exception text for specific error information. 


^ virtual IGraphicContext& 

draw( const IG3PointArc& arc); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to draw the graphic object. Refer to 
the exception text for specific error information. 


0 virtual IGraphicContext& 

draw( const IGChord& chord); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to draw the graphic object. Refer to 
the exception text for specific error information. 


[Ji] virtual IGraphicContext& 

draw( const IGString& graphicstring); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to draw the graphic object. Refer to 
the exception text for specific error information. 


|| virtual IGraphicContext& 

draw( const IGList& list); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to draw the graphic object. Refer to 
the exception text for specific error information. 


Qj] virtual IGraphicContext& 

draw( const IGRegion& region); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to draw the graphic object. Refer to 
the exception text for specific error information. 
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Drawing Attributes 

Use these members to set and query the current drawing attributes for the graphic context. 


backgroundColor 

Returns the current background color. 


virtual IColor Supported On: 

backgrounded or () const; PM 

backgroundMixMode 

Returns the current background mix mode. 


virtual IGraphicBundle::BackgroundMixMode 
backgroundMixMode() const; 


Supported On: 

PM 


drawOperation 

Returns the current draw operation. 


virtual IGraphi cBundl e:: DrawOperation Supported On: 

drawOperation() const; PM 

Returns the current fill color. 


virtual IColor Supported On: 

fill Col or() const; PM 

.Returns the current fill pattern. 


virtual unsigned long 
fi11 Pattern() const; 


Supported On: 

PM 


graphicBundle 

Queries the current attributes set for the graphic context and returns them as a bundle. 


virtual IGraphicBundle 
graphicBundle() const; 

.Returns the current pen mix mode. 


Supported On: 

PM 


virtual IGraphicBundle::MixMode 
mixMode() const; 


Supported On: 

PM 
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Exceptions 

IAccessError An error occured while attempting to set the mix mode. Refer to the 

exception text for specific error information. 


_ Returns the current fill pattern origin point. The pattern origin defines a point from 
which the pen and fill patterns spread horizontally and vertically. The lower-left 
corner is aligned on this point and is expressed in world coordinate space. 

virtual IPoint Supported On: 

patternOrigin() const; PM 


Exceptions 

IAccessError An error occurred while attempting to query the pattern origin. Refer to 

the exception text for specific error information. 


Returns the current pen color. 


virtual IColor 
penColor() const; 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to query the pen color. Refer to the 
exception text for specific error information. 


penEndingStyle 

Returns the current pen-ending style. 


virtual IGraphicBundle::PenEndingStyle 
penEndingStyle() const; 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to query the pen-ending style. Refer to 
the exception text for specific error information. 


penJoiningStyle 

Returns the current pen-joining style. 


virtual IGraphicBundle::PenJoiningStyle 
penJoiningStyle() const; 


Supported On: 

PM 
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Exceptions 

IAccessError 


An error occurred while attempting to query the pen-joining style. Refer to 
the exception text for specific error information. 


—Returns the current pen pattern. 


virtual unsigned long 
penPattern() const; 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to query the pen pattern. Refer to the 

exception text for specific error information. 


Returns the current pen type. 


virtual IGraphicBundle::PenType 
penType() const; 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to query the pen type. Refer to the 
exception text for specific error information. 


.Returns the current pen width. 


virtual unsigned long 
penWidth() const; 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to query the pen width. Refer to the 
exception text for specific error information. 


setBackgroundColor 

Sets the current background color. 


virtual IGraphicContext& 

setBackgroundColor( const IColor& backgroundColor); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to set the background color. Refer to 
the exception text for specific error information. 
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set Backg rou nd M ixMode 

Sets the current background mix mode. 


virtual IGraphicContext& 
setBackgroundMixMode( 

IGraphicBundle::BackgroundMixMode backgroundMixMode); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to set the background mix mode. Refer 
to the exception text for specific error information. 


setDrawOperation 

Sets the current draw operation for closed figures (frame, fill, or fill and frame). 


virtual IGraphicContext& 
setDrawOperation( 

IGraphicBundle::DrawOperation drawOperation); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to set draw operation. Refer to the 
exception text for specific error information. 


__Sets the current fill color. 


virtual IGraphicContext& 

setFi 11 Col or( const IColor& fill Col or); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the fill color. Refer to the 

exception text for specific error information. 


_ Sets the current fill pattern. 


virtual IGraphicContext& 

setFi11 Pattern( unsigned long fi11 Pattern); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to set the fill pattern. Refer to the 
exception text for specific error information. 


setGraphicBundle 

Sets the drawing attributes for the graphic context to those you set in the graphic 
bundle. 
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virtual IGraphicContext& Supported On: 

setGraphicBundle( const IGraphicBundl e& graphicBundle); PM 

_Sets the current mix mode. 


virtual IGraphicContext& Supported On: 

setMixMode( IGraphicBundle: :MixMode mixMode); PM 


Exceptions 

IAccessError 


An error occurred while attempting to set the mix mode. Refer to the 
exception text for specific error information. 


setPatternOrigin 

Sets the current fill pattern origin point. 


virtual IGraphicContext& 
setPatternOrigin( const IPoint& point); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the pattern origin. Refer to the 

exception text for specific error information. 


— Sets the current pen color. 


virtual IGraphicContext& 
setPenColor( const IColor& penColor); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to set the pen color. Refer to the 
exception text for specific error information. 


setPenEndingStyle 

Sets the current pen-ending style. The pen width must be greater than 1 for the 
pen-ending style to have an effect. 


virtual IGraphicContext& 
setPenEndingStyle( 

IGraphicBundle::PenEndingStyle penEndingStyle); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the pen-ending style. Refer to 

the exception text for specific error information. 
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setPenJoiningStyle 

Sets the current pen-joining style. The pen width must be greater than 1 for the 
pen-joining style to have an effect. 

virtual IGraphicContext& Supported On: 

setPenJoiningStyle( PM 

IGraphicBundle::PenJoiningStyle penJoiningStyle); 

Exceptions 

IAccessError An error occurred while attempting to set the pen-joining style. Refer to 

the exception text for specific error information. 


setPenPattern 

Sets the current pen pattern. 


virtual IGraphicContext& 

setPenPattern( unsigned long penPattern); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to set the pen pattern. Refer to the 
exception text for specific error information. 


...Sets the current pen type. The pen width must be 1 for a pen type other than solid 
to be used. 


virtual IGraphicContext& 

setPenType( IGraphicBundle::PenType penType); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the pen type. Refer to the 

exception text for specific error information. 


Sets the current pen width. 


virtual IGraphicContext& 

setPenWidth( unsigned long width); 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to set the pen width. Refer to the 
exception text for specific error information. 
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Font Operations 

Use these members to set and query information for the font that is used by the graphic context 
when drawing text. 

_ Returns the font currently set in the graphic context. 

virtual IFont Supported On: 

currentFont() const; PM 

Returns true if a font has been set for the graphic context. If the default font is 
being used, the function returns false. 

virtual IBase: :Boolean Supported On: 

hasFont() const; PM 

_Sets the graphic context's current font to the system default font. 


virtual IGraphicContext& 
resetFont(); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to reset the font. Refer to the 

exception text for specific error information. 


...Sets the graphic context's current font to the font specified. 


virtual IGraphicContext& 
setFont( const IFont& font); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the font. Refer to the exception 

text for specific error information. 


Hit Testing 

Hit testing is the process of determining which graphic objects, if any, are contained within an 
area of interest. When you select an area of interest on the screen, you usually move the pointer 
to the applicable point and signal (by clicking the mouse, for example) that this is the graphic 
object you want. The area of interest is a small rectangle centered at the hit point; its size is 
determined by the hit aperture size. The hit testing process draws graphic objects without 
rendering them on the screen. 

Use these members to provide hit testing support for graphic objects in other classes. Normally, 
you do not need to call these functions to perform hit testing. Instead, use IGraphic::contains, or 
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IGList::topGraphicUnderPoint, IGList::bottomGraphicUnderPoint, or use the IGList hit cursor to 
perform hit testing. 


hitApertu reSize 

Returns the current hit aperture size. 


virtual ISize Supported On: 

hitApertureSize() const; PM 

Returns the current hit point. 


virtual IPoint 
hitPoint() const; 


setHitApertu reSize 

Sets the size of the area around the hit point to use for determining hit tests. 


Supported On: 

PM 


virtual IGraphicContext& 

setHitApertureSize( const ISize& hitSize); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the hit aperture size. Refer to 

the exception text for specific error information. 


_Sets the current hit-point. Typically, this hit point is the point generated when the 
user presses a mouse button. 


virtual IGraphicContext& 

setHitPoint( const IPoint& hitPoint); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to set the hit point. Refer to the 

exception text for specific error information. 


startHitTesting 

Starts the hit-testing process. Any graphics drawn using this graphic context after this 
function has been called sets its selection state to true if the current hit point is 
contained within the graphic. Draw functions called after this function call are not 
visible. 


virtual IGraphicContext& 
startHitTesting(); 


Supported On: 

PM 


© IBM Corp. 1992, 1995 


IGraphicContext 739 





IGraphicContext 


Exceptions 

IAccessError An error occurred while attempting to start hit-testing. Refer to the 

exception text for specific error information. 


stopHitTesting 

Stops the hit testing process. All subsequent draw functions are visible. 


virtual IGraphicContext& 
stopHitTesting(); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to stop hit-testing. Refer to the 

exception text for specific error information. 


Mapping Modes 

Use these members to define the unit of measure used to map between the page space and the 
device space. The supported mapping modes are as follows: 


pels 

lowMetric 

highMetric 

lowEnglish 

highEnglish 

twips 

isotropic 


Pel Coordinates. This is the default when the graphic context is created. 
Units of 0.1 millimeter. 

Units of 0.01 millimeter. 

Units of 0.01 inch. 

Units of 0.001 inch. 

Units of 1/1440 inch. 

Logical units in the x-direction and y-direction are equal when mapping 
between page space and device space. The aspect ratio is preserved. 


mappingMode 

Retrieves the units defined for the graphic context. 


virtual MappingMode 
mappingMode() const; 


Supported On: 

PM 


Exceptions 

IAccessError 


An error occurred while attempting to query the mapping mode. Refer to 
the exception text for specific error information. 


setMappingMode 

Sets the units for the graphic context. 


virtual IGraphicContext& 
setMappingMode( MappingMode mappingMode = pels); 


Supported On: 

PM 
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Exceptions 

IAccessError An error occurred while attempting to set the mapping mode. Refer to the 

exception text for specific error information. 


Region Operations 

Use these members to query and set a graphic context's clip region. A region is an area in 
device space that is defined by one or more rectangular areas. You can use a region to 
determine the clip area used when drawing on a device. When you use a region as a clip region, 
the areas that are included in a region allow graphics that are contained or intersect the region to 
be output to the device. Areas outside of the clip region are not output to the device. 


clearClipRegion 

Clears the current clip region. 


virtual IGraphicContext& 
clearClipRegion(); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to clear the clip region. Make sure you 

are not simultaneously using the graphic context in another thread. 


_ Returns a handle to the current clip region. If you have not set a region as the clip 
region then a null handle is returned. 


virtual IRegionHandle 
clipRegion() const; 


Supported On: 

PM 


setClipRegion 

Q virtual IGraphicContext& Supported On: 

setCl i pRegion ( const IRegionHandl e& region); PM 

Sets the argument region as the new clip region for the graphic context. 

Exceptions 

IAccessError An error occurred while attempting to set the clipping region. Refer to the 

exception text for specific error information. 


§ virtual IGraphicContext& Supported On: 

setCl i pRegion ( const IGRegion& region); PM 

Sets the argument region as the new clip region for the graphic context. 
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Exceptions 

IAccessError An error occurred while attempting to set the clipping region. Refer to the 

exception text for specific error information. 


World Space Transformation 

Use these members to set and query the current world coordinate space transform matrix. 


setWorldTransformMatrix 

Sets the world coordinate space transform matrix using the specified transform 
method. 


virtual IGraphicContext& Supported On: 

setWorldTransformMatrix( PM 

const ITransformMatnx& transformMatrix, 

IGraphic::TransformMethod method = IGraphic::replace); 


Exceptions 

IAccessError An error occurred while attempting to set the world coordinate space 

transform matrix. Refer to the exception text for specific error information. 


worldTransformMatrix 

Returns the current world coordinate space transform matrix. 


virtual ITransformMatrix 
worldTransformMatrix() const; 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to query the world coordinate space 

transform matrix. Refer to the exception text for specific error information. 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



MappingMode 

MappingMode { 

pels, lowMetric, highMetric, lowEnglish, highEnglish, 

twips, isotropic 

}; 
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IGraphicPushButton 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

IPushButton 

IGraphicPushButton 


_.None. 
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The IGraphicPushButton class creates and manages graphic push button control 
windows. The standard push button generates an ICommandEvent (Vol. II). 
However, the application can change the window style value to generate a help event 
or system command event. To change the push button event (that is, message) 
processing, call IPushButton: :enableHelp (Vol. II) and 

IPushButton::enableSystemCommand (Vol. II). These functions add or remove the 
styles IPushButton::help (Vol. II) and IPushButton::systemCommand (Vol. II), 
respectively. For example: 

IGraphicPushButton pbCancel(ID_CANCEL, this, this, ID_SOMEBMP, 

IRectangle( 10 , 10 , 80 , 22 )); 


| Mohi The IGraphicPushButton control consists of an XmPushButton widget. The 

XmNlabelPixmap resource is set to the graphic specified on the constructor. 


744 Open Class Library Reference 








IGraphicPushButton 


@e AIX does not support dialog templates. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign 
IGraphicPushButton objects because both the copy constructor and assignment operator are 
private functions. 


IGraphicPushButton 

2 IGraphicPushButton( unsigned long id. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IResourceId& bitmapOrlconld, 

const IRectangle& initial = IRectangle ( ), 

const Style& style = defaultStyle ( )); 

Creates a graphic push button using the specified window ID, parent and owner 
windows, screen position and size, resource library with its specified icon or bitmap 
ID, and window style. If you have not already loaded the bitmap or icon and you 
want to load it from the resource library of your choice, use this constructor. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


§ IGraphicPushButton( unsigned long id. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

unsigned long bitmapOrlconld, 

const IRectangle& initial = IRectangle ( ), 

const Style& style = defaultStyle ( )); 

Creates a graphic push button with the specified window ID, parent and owner 
windows, screen position and size, default resource library with its specified icon or 
bitmap ID, and window style. If you have not already loaded the bitmap or icon and 
you want to load it from the default resource library, use this constructor. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 
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0 IGraphicPushButton( unsigned long id. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IBitmapHandle& bitmap = IBitmapHandle ( ), 
const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Creates a graphic push button with the specified window ID, parent and owner 
windows, screen position and size, bitmap, and window style. If you already have a 
bitmap handle, use this constructor to put the bitmap on the graphic push button. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


0 IGraphicPushButton( unsigned long id. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IPointerHandle& icon, 

const IRectangle& initial = IRectangle ( ), 

const Style& style = defaultStyle ( )); 

Creates a graphic push button with the specified window ID, parent and owner 
windows, screen position and size, icon, and window style. If you already have an 
icon handle, use this constructor to put the icon on a graphic push button. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


g IGraphicPushButton( unsigned long id. Supported On: 

IWindow* parentDialog); PM, Motif 


Creates a graphic push button object for the specified push button in a dialog 
template that has the icon or bitmap style. 


Exceptions 

IlnvalidParameter 

The parent window pointer specified was invalid. You must specify a 
valid IWindow pointer as the parent. 

IAccessError 

Control information could not be obtained from the system for the 
specified window. Verify that the specified ID and parentDialog 
combination refer to a valid push button control. 


^ IGraphicPushButton( const IWindowHandle& handle); Supported On: 

PM, Motif 
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Creates a graphic push button object for an existing bitmap or icon push button 
control with the specified window handle. 

Exceptions 

IAccessError Control information could not be obtained from the system for the 

specified window. Verify that the specified handle refers to a valid push 
button control. 


IGraphicPushButton 


virtual 

"IGraphicPushButtonO; 


Supported On: 

PM, Motif 


Graphic 

A graphic is an icon or bitmap that is displayed on a graphic push button. You can query the 
type, handle, or window of the current graphic and set a new graphic. 

Returns the handle of the currently set bit map. If no bit map is set into the graphic 
push button, an IBitmapHandle (Vol. II) is returned. 


IBi tmapHandle Supported On: 

bitmapO const; PM, Motif 

currentGraphicType 

Returns the current type of graphic set onto the graphic push button. The returned 
value is an enumerator provided by IGraphicPushButton::GraphicType (p. 753). 


GraphicType 

currentGraphicType() const; 


Supported On: 

PM, Motif 


graphicWindow 

Returns the IlconControl (p. 784) used for drawing the graphic. 

IIconControl & Supported On: 

graphicWindow() const; PM, Motif 

| Motif AIX does not support this function; therefore, it has no effect. 

Returns the handle of the currently set icon. If no icon is set into the graphic push 
button, an IlconControl (p. 784) is returned. 
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IPointerHandle 
icon() const; 

...Changes the stored graphic to the specified value. 


Supported On: 

PM. Motif 


[J virtual IGraphicPushButton& Supported On: 

setGraphic( const IPointerHandle& handle); PM, Motif 

Use this overload if you already have an icon handle for the icon you want to place 
on the graphic push button. 


| virtual IGraphicPushButton& Supported On: 

setGraphic( unsigned long bitmapOrlconld); PM, Motif 

Use this overload if you have not already loaded the bitmap or icon and you want to 
load it from the default resource library. 


0 virtual IGraphicPushButton& Supported On: 

setGraphic( const IResourceId& bi tmapOrlconld); PM, Motif 

Use this overload if you have not already loaded the bitmap or icon and you want to 
load it from the resource library of your choice. 


0 virtual IGraphicPushButton& Supported On: 

setGraphic( const I Bi tmapHandl e& handle); PM. Motif 

Use this overload if you already have a bitmap handle for the bitmap you want to 
place on the graphic push button. 

Graphic Size 

Use these style members to query and modify the style of a graphic push button object. 


disableSizeToGraphic 

Removes the style sizeToGraphic (p. 752). 


virtual IGraphicPushButton& Supported On: 

di sabl eSi zeToGraphi c(); PM, Motif Ignored 

I Motif AIX does not support this function; therefore, it has no effect. 

enableSizeToGraphic 

Adds or removes the style sizeToGraphic (p. 752). 


virtual IGraphicPushButton& 
enableSizeToGraphic( Boolean sizeToGraphic = true); 


Supported On: 

PM, Motif Ignored 
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j _ AIX does not support this function; therefore, it has no effect. 

isSizeToGraphic 

If the style sizeToGraphic (p. 752) is set, true is returned. 


Boolean 

isSizeToGraphic() const; 


Supported On: 

PM, Motif 


Margins 

The margin is the area between the graphic and the outside border of the push button. If you 
have not set the sizeToGraphic style, you can change the size of this area. 

_ Returns the currently set margin size. 


ISize Supported On: 

marginSizeO const; PM, Motif Ignored 


setMarginSize 

Changes the size of the margin for the graphic. This only has meaning if the 
sizeToGraphic style is not set. The height of the ISize will be used for both the top 
and bottom of the button, and the width value of the ISize will be used for the left 
and right sides. 

IGraphicPushButton& Supported On: 

setMarginSize( const ISize& size); PM. Motif Ignored 


Styles 

These style members provide valid styles for IGraphicPushButton; :setDefaultStyle and for the 
constructor of the IGraphicPushButton (p. 744) class. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

_. Returns the default style. The default style is classDefaultStyle (p. 752) unless you 
have changed it using setDefaultStyle (p. 750). 
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static Style 
defaultStyle(); 


Supported On: 

PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent graphic push buttons. Use the styles provided 
by IGraphicPushButton (p. 752) to specify the default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Window Positioning 

Use these members to manipulate the size and position of windows. 
_ Changes the position and size of the window. 


virtual IWindow& 

moveSizeTo( const IRectangle& aRectangle); 


Supported On: 

Motif 


Inherited Public Functions 


IPushButton 

addB order 

disableSystemCommand 

isDefault 

convertToGUIStyle 

enableDefault 

isHelp 

defaultStyle 

enableHelp 

isSystemCommand 

disableDefault 

enableSystemCommand 

removeB order 

disableHelp 

hasB order 

setDefaultStyle 


IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableNotification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 
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IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Layout Support 

Layout is information used by the canvas classes to provide dialog-like behavior. 

calcMinimumSize 

Returns the recommended minimum size of this graphic push button control. The 
size is based on the actual size of the stored graphic. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IPushButton 

calcMinimumSize 

passEventT oOwner 

registerCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 
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Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
Styles 

These style members provide valid styles for IGraphicPushButton: :setDefaultStyle and for the 
constructor of the IGraphicPushButton (p. 744) class. 


classDefaultStyle 

Specifies the original default style for this class, which is IWindow::visible. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM. Motif 


sizeToGraphic 

Displays the graphic on the push button using the graphic’s actual size. If the graphic 
is larger than the push button, the graphic is clipped. If the graphic is smaller than 
the push button, the graphic is centered on the push button. If you do not specify this 
style, the graphic is stretched to fill the push button within its border. 

static const Style Supported On: 

sizeToGraphic; PM. Motif 


Inherited Public Data 


IPushButton 

classDefaultStyle 

defaultButton 

help 


IButton 

buttonClickld 

noPointerFocus 



ITextControl 

textld 




IControl 

group 

tabStop 
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IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IGraphicPushButton contains the following nested classes: 
IGraphicPushButton: :Style (see page 754) 


GraphicType { 
bitmapType, 
iconType 
}; 


These enumerators specify the current type of graphic set onto the graphic push 
button: 

bitmapType 

Specifies that a bitmap is set onto the graphic push button. If you do not 
specify a handle or resource ID when constructing the graphic push button 
object, an IBitmapHandle (Vol. II) is the default graphic. This is the default 
style. 

iconType 

Specifies an icon is set onto the graphic push button. 
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IGraphicPushButton::Style 


IBase 

IBitFlag 

IGraphicPushButton: :Style 


_.None. 

_ igraphbt.hpp 

The nested class IGraphicPushButton::Style provides a set of valid styles for the 
IGraphicPushButton (p. 744) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IGRectangle 


IBase 

IVBase 

IGraphic 

IGRectangle 


_.None. 


_igrect.hpp 

Member 

Page 

Constructor 

756 

drawOn 

757 

enclosingRect 

757 

operator != 

756 

operator = 

756 


Member 

Page 

operator == 

756 

rounding 

757 

setEnclosingRect 

758 

setRounding 

757 

“IGRectangle 

757 


Objects of this class are used to draw two-dimensional rectangles. An IGRectangle 
may be filled, framed or filled and framed. 

You can optionally round the corners of the rectangle by specifying the full length of 
the horizontal and vertical axes of an ellipse. The corners of the rectangle are 
rounded by a quarter of the ellipse. 

When you draw an IGRectangle, the following graphic bundle drawing attributes 
affect its appearance: 

• Draw operation 

• Pen color 

• Fill color 

• Background color 

• Mix mode 

• Background mix mode 

• Pen width 

• Pen type 

• Pen joining style 

• Pen pattern 

• Fill pattern 

• Pattern origin 
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Public Functions 
Comparisons 

Use these members to compare two IGRectangle objects. 

_ Returns true if the rectangles are not identical (includes the graphic bundle attributes 
and the transform matrix). 

I Base:: Boolean Supported On: 

operator ! = ( const IGRectangle& gRectangle) const; PM 

_ Returns true if the rectangles are identical (includes the graphic bundle attributes 
and the transform matrix). 

I Base:: Boolean Supported On: 

operator ==( const IGRectangle& gRectangle) const; PM 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 


IGRectangle 

[J IGRectangle( const IRectangle& rectangle = IRectangle ( )); Supported On: 

PM 

Use this function to construct a IGRectangle object from a IRectangle object. The 
position and size of the IGRectangle is set by the argument IRectangle. 

rectangle (Optional) A IRectangle object specifying size and position. 

| IGRectangle( const IGRectangle& gRectangle); Supported On: 

PM 

Use this function to construct a IGRectangle object from another IGRectangle object. 
gRectangle A reference to a IGRectangle object. 

_Use this function to assign a IGRectangle object to another IGRectangle object. 


IGRectangl e& Supported On: 

operator =( const IGRectangle& gRectangle); PM 


756 


Open Class Library Reference 



IGRectangle 


"IGRectangle 


virtual 

"IGRectangleO; 


Supported On: 

PM 


Corner Rounding 

Use these members to round the comers of the IGRectangle object. You control the comer 
rounding by specifying the full length of the horizontal and vertical axes of an ellipse. The 
comers of the box are rounded by a quarter of the ellipse. If the horizontal and vertical axes are 
equal, the rectangle is rounded by using a quarter circle. 

-Returns the full length of the horizontal and vertical axes used to detemrine corner 
rounding. By default, the corners of the rectangle are not rounded. 

virtual IPair Supported On: 

rounding() const; PM 

- Sets the full length of the horizontal and vertical axes of the ellipse used to 
determine corner rounding. 

virtual IGRectangle& Supported On: 

setRounding( const IPair& ellipseAxis = IPair (0,0)); PM 


Drawing 

Use these members to render an IGRectangle object on a device. 

Draws the rectangle on the device associated with the graphic context. 


virtual IGRectangle& 

drawOn( IGraphicContext& graphicContext); 


Supported On: 

PM 


Enclosing Rectangle 

Use these members to define the size and position of the IGRectangle object. 


enclosingRect 

Returns the dimensions of the IGRectangle. 


virtual IRectangle 
enclosingRect() const; 


Supported On: 

PM 
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setEnclosingRect 

Sets the dimensions of the IGRectangle. 


virtual IGRectangle& 

setEnclosingRect( const IRectangle& rectangle); 


Supported On: 

PM 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IGRegion 


IBase 

IVBase 

IGraphic 

IGRegion 


_.None. 


_ igregion.hpp 

Member 

Page 

Constructor 

760 

clear 

762 

drawOn 

762 

moveBy 

775 

operator &= 

764 

operator += 

766 


Member 

Page 

operator -= 

767 

operator = 

761 

operator const IRegionHandle 

761 

operator *= 

768 

“IGRegion 

761 


Objects of IGRegion are graphic objects that may be composed of one or more closed 
figures. You can use a IGRegion to construct a shape from one or more closed 
figures. You can draw the region on a graphic context or used as a clip region when 
drawing other graphic objects on a graphic context. 

When you draw a IGRegion, the following graphic bundle drawing attributes affect a 
region's appearance: 

• Pen color 

• Mix mode 

• Pen pattern 

• Pattern origin 

The coordinates you use to define a region are specified in device space. For this 
reason the world transform functions that are declared in IGraphic have no effect and 
are overridden as private functions in IGRegion. 

Constructing an IGRegion is a simple process that involves adding, subtracting, 
logical XORing or logical ANDing a closed figure or another IGRegion. 
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Public Functions 
Constructors 

You can construct, destruct, copy, and assign objects of this class. 


IGRegion 

[] IGRegion(); Supported On: 

PM 

Use the default constructor to create a IGRegion object. The region is initially 
empty. 

Exceptions 

IAccessError An error occurred while attempting to create the region. Refer to the 

exception text for specific error information. 


§ IGRegion( const IRegionHandl e& regionHandle); Supported On: 

PM 

Use this function to construct a IGRegion object from a IRegionHandle object. The 
IGRegion is initialized to the region defined by the region handle. 

regionHandle A handle to an existing region. 


Exceptions 

IAccessError An error occurred while attempting to create the region. Refer to the 

exception text for specific error information. 


g IGRegion( const IGRegion& region); Supported On: 

PM 

Use this function to construct a IGRegion object from another IGRegion object. 
region A reference to a IGRegion object. 

Exceptions 

IAccessError An error occurred while attempting to create the region. Refer to the 

exception text for specific error information. 


0 IGRegion( const IGraphicContext& graphicContext, Supported On: 

const IRectangle& rectangle); PM 
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Use this function to create a IGRegion object from a IGraphicContext object and a 
IRectangle object. The region is created from the area specified by the rectangle in 
device coordinates for the argument graphic context. 

graphicContext A IGraphicContext object. 

rectangle Rectangular area in device coordinates. 


Exceptions 

IAccessError An error occurred while attempting to create the region. Refer to the 

exception text for specific error information. 


g IGRegion( const IWindowHandle& windowHandle); Supported On: 

PM 

Use this function to construct a IGRegion object from a IWindowHandle object. The 
region is created from the windows update region. 

windowHandle Window handle from which the update region is created. 

Exceptions 

IAccessError An error occurred while attempting to create the region. Refer to the 

exception text for specific error information. 


.. Use this function to construct a IGRegion object from another IGRegion object. 

IGRegion& Supported On: 

operator =( const IGRegion& region); PM 

IGRegion 


virtual 

"IGRegionO; 


Supported On: 

PM 


Conversion 

Use these members to access the IGRegion as an IRegionHandle object. 

operator const IRegionHandle 

Returns a handle to the IGRegion. 

operator const IRegionHandleO const; Supported On: 

PM 
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Drawing 

Use these members to render an IGRegion object on a device. 

Draws the the region on the device associated with the graphic context. 


virtual IGRegion& 

drawOn( IGraphicContext& graphicContext); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to draw the region. Refer to the 

exception text for specific error information. 


Modifying a Region 

Use these members to modify the area of a region. 
Sets the region to a null region. 


virtual IGRegion& 
clear(); 


Supported On: 

PM 


Operators with Closed Shapes 

Use these members to combine a closed shape with a region. 
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Figure 8. Combining Overlapping Regions 
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[ Combining Disjoint Regions 
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Figure 9. Combining Disjoint Regions 


operator &= 

H IGRegion& Supported On: 

operator &=( const IGChord& chord); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the chord. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Q IGRegion& Supported On: 

operator &=( const IGRectangle& rect); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the rectangle. 
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Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


0 IGRegion& Supported On: 

operator &=( const IGPie& pie); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the pie. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Q IGRegion& Supported On: 

operator &=( const IGPolygon& polygon); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the polygon. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

0 IGRegion& Supported On: 

operator &=( const IGE11 ipse& ellipse); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the ellipse. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

^ IGRegion& Supported On: 

operator &=( const IGRegion& region); PM 

Sets the region to the area defined by the intersection of the two regions. 

Exceptions 

IAccessError An error occurred while attempting to combine the regions. Refer to the 

exception text for specific error information. 
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operator += 

[J IGRegion& Supported On: 

operator +=( const IGEllipse& ellipse); PM 

Sets the region to the area defined by the union of the region and the area of the 
ellipse. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

2 IGRegion& Supported On: 

operator +=( const IGRectangle& rect); PM 

Sets the region to the area defined by the union of the region and the area of the 
rectangle. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

2 IGRegion& Supported On: 

operator +=( const IGPie& pie); PM 

Sets the region to the area defined by the union of the region and the area of the pie. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Q IGRegion& Supported On: 

operator +=( const IGChord& chord); PM 

Sets the region to the area defined by the union of the region and the area of the 
chord. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


g IGRegion& 

operator +=( const IGPolygon& polygon); 


Supported On: 

PM 
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Sets the region to the area defined by the union of the region and the area of the 
polygon. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


^ IGRegion& Supported On: 

operator +=( const IGRegion& region); PM 

Sets the region to the area defined by the union of the two regions. 

Exceptions 

IAccessError An error occurred while attempting to combine the regions. Refer to the 

exception text for specific error information. 

operator-= 

[] IGRegion& Supported On: 

operator -=( const IGEllipse& ellipse); PM 

Sets the region to the area defined by the region minus the area of the ellipse. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

@ IGRegion& Supported On: 

operator -=( const IGRectangle& rect); PM 

Sets the region to the area defined by the region minus the area of the rectangle. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


g IGRegion& Supported On: 

operator -=( const IGPie& pie); PM 

Sets the region to the area defined by the region minus the area of the pie. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 
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Q IGRegion& Supported On: 

operator -=( const IGChord& chord); PM 

Sets the region to the area defined by the region minus the area of the chord. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


0 IGRegion& Supported On: 

operator -=( const IGPolygon& polygon); PM 

Sets the region to the area defined by the region minus the area of the polygon. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


^ IGRegion& Supported On: 

operator -=( const IGRegion& region); PM 

Sets the region to the area defined by the target region minus the area of the operand 
region. 

Exceptions 

IAccessError An error occurred while attempting to combine the regions. Refer to the 

exception text for specific error information. 

operator A = 

[J IGRegion& Supported On: 

operator /v =( const IGChord& chord); PM 

Sets the region to the area defined by the logical xor of the region and the chord. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


| IGRegion& Supported On: 

operator A =( const IGRectangle& rect); PM 

Sets the region to the area defined by the logical xor of the region and the rectangle. 
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Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


0 IGRegion& Supported On: 

operator /s =( const IGPie& pie); PM 

Sets the region to the area defined by the logical xor of the region and the pie. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


0 IGRegion& Supported On: 

operator /s =( const IGPolygon& polygon); PM 

Sets the region to the area defined by the logical xor of the region and the polygon. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


0 IGRegion& Supported On: 

operator A =( const IGEllipse& ellipse); PM 

Sets the region to the area defined by the logical xor of the region and the ellipse. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


@ IGRegion& Supported On: 

operator *={ const IGRegion& region); PM 

Sets the region to the area defined by the logical xor of the two regions. 


Exceptions 

IAccessError An error occurred while attempting to combine the regions. Refer to the 

exception text for specific error information. 


Operators with Other IGRegions 

Use these members to combine two IGRegions objects. See Figure 8 on page 763 and Figure 9 
on page 764. 
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operator &= 

[J IGRegion& Supported On: 

operator &=( const IGRegion& region); PM 

Sets the region to the area defined by the intersection of the two regions. 

Exceptions 

IAccessError An error occurred while attempting to combine the regions. Refer to the 

exception text for specific error information. 

Q IGRegion& Supported On: 

operator &=( const IGRectangl e& rect); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the rectangle. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

Q IGRegion& Supported On: 

operator &=( const IGPie& pie); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the pie. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Q IGRegion& Supported On: 

operator &=( const IGChord& chord); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the chord. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


g IGRegion& 

operator &=( const IGPolygon& polygon); 


Supported On: 

PM 
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Sets the region to the area defined by the intersection of the region and the area of 
the polygon. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


^ IGRegion& Supported On: 

operator &=( const IGEllipse& ellipse); PM 

Sets the region to the area defined by the intersection of the region and the area of 
the ellipse. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Q IGRegion& Supported On: 

operator +=( const IGRegion& region); PM 

Sets the region to the area defined by the union of the two regions. 

Exceptions 

IAccessError An error occurred while attempting to combine the regions. Refer to the 

exception text for specific error information. 

@ IGRegion& Supported On: 

operator +=( const IGRectangle& rect); PM 

Sets the region to the area defined by the union of the region and the area of the 
rectangle. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

0 IGRegion& Supported On: 

operator +=( const IGPie& pie); PM 

Sets the region to the area defined by the union of the region and the area of the pie. 
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Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Q IGRegion& Supported On: 

operator +=( const IGChord& chord); PM 

Sets the region to the area defined by the union of the region and the area of the 
chord. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

0 IGRegion& Supported On: 

operator +=( const IGPolygon& polygon); PM 

Sets the region to the area defined by the union of the region and the area of the 
polygon. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

@ IGRegion& Supported On: 

operator +=( const IGEllipse& ellipse); PM 

Sets the region to the area defined by the union of the region and the area of the 
ellipse. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


[J IGRegion& Supported On: 

operator -=( const IGRegion& region); PM 

Sets the region to the area defined by the target region minus the area of the operand 
region. 
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Exceptions 

IAccessError An error occurred while attempting to combine the regions. Refer to the 

exception text for specific error information. 

@ IGRegion& Supported On: 

operator -=( const IGRectangle& rect); PM 

Sets the region to the area defined by the region minus the area of the rectangle. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 

0 IGRegion& Supported On: 

operator -=( const IGPie& pie); PM 

Sets the region to the area defined by the region minus the area of the pie. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Q IGRegion& Supported On: 

operator -=( const IGChord& chord); PM 

Sets the region to the area defined by the region minus the area of the chord. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


@ IGRegion& Supported On: 

operator -=( const IGPolygon& polygon); PM 

Sets the region to the area defined by the region minus the area of the polygon. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


^ IGRegion& Supported On: 

operator -=( const IGEllipse& ellipse); PM 

Sets the region to the area defined by the region minus the area of the ellipse. 
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Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


operator A = 


[] IGRegion& Supported On: 

operator A =( const IGRegion& region); PM 

Sets the region to the area defined by the logical xor of the two regions. 


Exceptions 

IAccessError An error occurred while attempting to combine the regions. Refer to the 

exception text for specific error information. 


| IGRegion& Supported On: 

operator /v =( const IGRectangle& rect); PM 

Sets the region to the area defined by the logical xor of the region and the rectangle. 

Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Q IGRegion& Supported On: 

operator /v =( const IGPie& pie); PM 

Sets the region to the area defined by the logical xor of the region and the pie. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


[[] IGRegion& Supported On: 

operator /v =( const IGChord& chord); PM 

Sets the region to the area defined by the logical xor of the region and the chord. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 
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0 IGRegion& Supported On: 

operator /s =( const IGPolygon& polygon); PM 

Sets the region to the area defined by the logical xor of the region and the polygon. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


^ IGRegion& Supported On: 

operator /s =( const IGE11 ipse& ellipse); PM 

Sets the region to the area defined by the logical xor of the region and the ellipse. 


Exceptions 

IAccessError An error occurred while attempting to combine the area with the region. 

Refer to the exception text for specific error information. 


Positioning 

Use these members to move an IGegion object in device space. 

_Moves the region by the amount specified by the argument point. 


virtual IGRegion& 
moveBy( const IPoint& point); 


Supported On: 

PM 


Exceptions 

IAccessError An error occurred while attempting to move the region. Refer to the 

exception text for specific error information. 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 


© IBM Corp. 1992, 1995 


IGRegion 775 








IGRegion 


IVBase 


asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IGString 


IBase 

IVBase 

IGraphic 

IGString 


_.None. 


_igstring.hpp 

Member 

Page 

Constructor 

780 

clippingRect 

779 

drawOn 

781 

font 

781 

hasFont 

781 

isClippingRectSet 

779 

moveTo 

782 

operator != 

779 

operator = 

780 


Member 

Page 

operator == 

779 

position 

782 

removeFont 

781 

resetClippingRect 

779 

setClippingRect 

779 

setFont 

781 

setText 

782 

text 

782 

'IGString 

781 


The IGString class is a graphic object class that allows you to draw text. An 
IGString object can optionally have a font associated with it that is used when you 
draw the IGString object. If you do not supply a font object for the IGString object, 
the graphic context current font is used when you draw the IGString object. 

In all the constructors you provide a location point of where the text drawing starts. 
Text alignment and font direction determine where the text is positioned in relation to 
the location point you specify. 

When you draw a IGString object, the following graphic bundle drawing attributes 
affect its appearance: 

• Pen color 

• Background color 

• Mix mode 

• Background mix mode 
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Public Functions 
Clipping Rectangle 

Use these members to set, query, and remove the clipping rectangle used when drawing the text. 
If a clipping rectangle is set, the text is clipped to the boundary to the rectangle. 

- Returns the clipping rectangle. If a clipping rectangle has not been set, a default 
rectangle (0,0,0,0) is returned. 

virtual IRectangle 
cl ippingRect() const; 

isClippingRectSet 

Returns true if a clipping rectangle is set. 

virtual IBase::Boolean 
isClippingRectSet() const; 

resetClippingRect 

Removes the clipping rectangle. 

virtual IGString& Supported On: 

resetClippingRect(); PM 


Supported On: 

PM 


Supported On: 

PM 


setClippingRect 

Sets the clipping rectangle used when drawing the text. 


virtual IGString& 

setClippingRect( const IRectangle& rectangle); 


Supported On: 

PM 


Comparisons 

Use these members to compare two IGString objects. 

_ Returns true if the text objects are not identical (includes location, font, the graphic 
bundle attributes and the transform matrix). 

IBase::Boolean Supported On: 

operator ! = ( const IGString& graphicstring) const; PM 

_ Returns true if the text objects are identical (includes location, font, the graphic 
bundle attributes and the transform matrix). 


© IBM Corp. 1992, 1995 


IGString 779 



IGString 


I Base:: Boolean Supported On: 

operator ==( const IGStri ng& graphicstring) const; PM 

Constructors 

You can construct, destruct, copy, and assign object of this class. 

IGString 

| IGString( const IString& string, 
const IPoint& point, 
const IFont& font); 

Use this function to construct a IGString object from a IString, a IPoint object 
specifying where to draw the string, and a IFont object specifying the font to use 
when you draw the IGString object. 

string Characters to be drawn. 

point Location of where to draw the characters. 

font (Optional) Font used when drawing the characters. 


Supported On: 

PM 


2 IGStri ng ( const IString& string, Supported On: 

const I Poi nt& point = IPoint ( )); PM 

Use this function to construct a IGString object from a IString object and optionally a 
IPoint object specifying where to draw the string 

string Characters to be drawn. 

point Location of where to draw the characters. 

0 IGStri ng ( const IGStri ng& graphicstring); Supported On: 

PM 

Use this function to construct a IGString object from another IGString object. 
graphicString A reference to a IGString object. 

.Use this function to assign a IGString object to another IGString object. 

IGString& Supported On: 

operator =( const IGString& graphicstring); PM 
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"IGString 


virtual 

'IGStringO ; 


Supported On: 

PM 


Drawing 

Use these members to render an IGString object on a device. 

Draws the string at the current position. The string is drawn using the object's font 
if set. If you have not specified a font for this object (either in the constructor or via 
the setFont function), then the text is drawn using the graphic context current font. 

virtual IGString& Supported On: 

drawOn( IGraphicContext& graphi cContext); PM 


Font 

Use these members to set, query, and remove the font used when you draw an IGString object. 
If you have not set a font for an IGString object, the graphic context's current font is used when 
you draw an IGString object. 

Returns the current font being used to draw the text. If you did not set a font on the 
object or constructed the object with a font object, this function returns the system 
default font. 


virtual I Font Supported On: 

font() const; PM 

Returns true if a font was specified in the constructor or set using setFont function. 


virtual I Base:: Boolean Supported On: 

hasFont() const; PM 

—Removes the font object from the graphic text. The font is deleted. 


virtual IGString& Supported On: 

removeFont(); PM 

.Sets the font to be used when drawing the text. 


virtual IGString& 

setFont( const IFont& font); 


Supported On: 

PM 
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Text 

Use these members to set and query the text of an IGString object. 

.Sets the graphic object's text. 

Supported On: 

PM 


| virtual IGString& 

setText( const char* text); 


2 virtual IGString& 

setText( const IResourceId& text); 

Returns the graphic objects text. 


Supported On: 

PM 


virtual IString 
text() const; 


Supported On: 

PM 


Text Positioning 

Use these members to set and query the position of the text. 

Sets the starting location of where the text is to be drawn. 


virtual IGString& Supported On: 

moveTo( const IPoint& point); PM 

Returns the starting location of where the text is to be drawn. 


virtual IPoint 
position() const; 


Supported On: 

PM 


Inherited Public Functions 


IGraphic 

boundingRect 

isHitSelectable 

setHitSelectable 

contains 

isHitSelected 

setHitSelected 

drawOn 

removeGraphicBundle 

setld 

graphicBundle 

resetTransformMatrix 

setTransformMatrix 

hasGraphicBundle 

rotateBy 

setTransformMethod 

hasTransformMatrix 

scaleBy 

transformMatrix 

id 

setGraphicBundle 

transformMethod 
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IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IGraphic 

operator != 

operator = 

operator == 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IStaticText 

IBitmapControl 

IlconControl 


_.None. 


__iiconctl.hpp 


Member 

Page 

Constructor 

785 

calcMinimumSize 

789 

classDefaultStyle 

790 

con vertT oGUISty le 

787 

defaultStyle 

788 

icon 

787 


Member 

Page 

moveSizeTo 

788 

setDefaultStyle 

788 

setlcon 

787 

sizeToIcon 

790 

visibleRectangle 

784 

'IlconControl 

786 


Objects of the IlconControl class create and operate upon icon controls. You can also 
use this class to add text to an icon by calling ITextControl::setText (Vol. II). 

IMotifl AIX does not support system bitmaps and dialog templates. 


Public Functions 
Canvas Support 

These members override the inherited visibileRectangle function. 


visibleRectangle 

Returns a rectangle that represents the area of the window that is actually painted by 
the icon control. 


784 Open Class Library Reference 









IlconControI 


virtual IRectangle 
visibleRectangle() const; 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IlconControI 
objects because both the copy constructor and assignment operator are private functions. 


IlconControI 

Q IlconControI ( unsigned long id, Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IResourceId& iconld, 

const IRectangle& initial = IRectangle ( ), 

const Style& style = defaultStyle ( )); 

Create an icon control using the specified window id, parent and owner windows, 
resource library with its specified icon id, screen position and size, and window style. 
If you have not already loaded the resource, use this constructor. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


§ IlconControI ( unsigned long id, Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 
unsigned long iconld, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Create an icon control with the specified id, parent and owner windows, default 
resource library with its specified icon id, and window style. If you have not already 
loaded the icon and you want load it from the default resource library, use this 
constructor. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 
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0 IlconControI ( unsigned long id, Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IPointerHandle& iconld = IPointerHandle ( ), 
const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Create an icon control with the specified window id, parent and owner windows, icon, 
screen position and size, and window style. If you already have an icon handle, use 
this constructor. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


0 IlconControI ( unsigned long id, Supported On: 

IWindow* parent, PM 

IWindow* owner, 

ISystemPointerHandle::Identifier icon, 
const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Create an icon control with the specified window id, parent and owner windows, 
specified system icon, screen position and size, and window style. If you want to use 
a system icon, use this constructor. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


g IlconControI ( unsigned long id, Supported On: 

IWindow* parentDialog); PM, Motif 

Create an IlconControI object for the specified icon from the dialog control. 

^ IlconControI ( const IWindowHandl e& handle); Supported On: 

PM, Motif 


Create an IlconControI object for the specified icon window handle. 


IlconControI 


virtual 

'IlconControI(); 


Supported On: 

PM. Motif 
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Icons 

Use these functions to query and set the icon image in an icon control window. 
Returns the handle of the currently set icon. 


IPointerHandle Supported On: 

icon() const; PM. Motif 

Sets the icon image of the icon control window. 


Q virtual IlconControU Supported On: 

setIcon( const IPointerHandl e& handle); PM. Motif 

Set the icon using an existing icon handle. 

g virtual IlconControU Supported On: 

setIcon( unsigned long iconld); PM. Motif 

Set the icon using the default resource library with the specified icon id. 

g virtual IlconControU Supported On: 

setIcon( const IResourceId& iconld); PM. Motif 

Set the icon by specifying an IResourceld. If you want to load the icon from a 
specific resource library, use this function. 

0 virtual IlconControU Supported On: 

setIcon( ISystemPointerHandle:: Identifier icon); PM 

Set the icon using a system icon. 


Styles 

These style members provide valid styles for IlconControI::setDefaultStyle and for the 
constructor of the IlconControI (p. 784) class. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 


virtual unsigned long 
convertToGUIStyle( const IBitFlag& style, 

Boolean extendedOnly = false) const; 


Supported On: 

PM 
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—Returns the default style. This is classDefaultStyle (p. 790) unless you have 
changed it using setDefaultStyle (p. 788). 


static Style 
defaultStyle(); 


Supported On: 

PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent icon controls. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM. Motif 


Window Positioning 

Use these members to set the size and position of windows. 
—Changes the position and size of the window. 


virtual IIconControl& Supported On: 

moveSizeTo( const IRectangle& aRectangle); Motif 

|_J This IWindow function is overridden to handle icon sizing and positioning in Motif. 


Inherited Public Functions 


IBitmapControl 

bitmap 

defaultStyle 

setBitmap 

convertToGUIStyle 

moveSizeTo 

setDefaultStyle 


IStatieText 

alignment 

enableFillBackground 

isStrikeout 

backgroundColor 

enableHalftone 

isUnderscore 

convertToGUIStyle 

enableStrikeout 

limit 

defaultStyle 

enableUnderscore 

moveSizeTo 

disableFillBackground 

fiUColor 

resetFillColor 

disableHalftone 

foregroundColor 

setAlignment 

disableStrikeout 

hasFillBackground 

setDefaultStyle 

disableUnderscore 

isHalftone 

setFillColor 
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ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Layout Support 

Layout is information used by the canvas classes to provide dialog-like behavior. 

calcMinimumSize 

Returns the minimum size this icon control can be based on the actual size of the 
currently set icon. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The call to determine the size of the icon failed. The icon may be 

corrupted. 


© IBM Corp. 1992, 1995 


IlconControI 789 







IlconControI 


Inherited Protected Functions 


IBitmapControl 

calcMinimumSize 




IStatieText 

calcLimitSize 

calcMinimumSize 

passEventToOwner 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
Styles 

These style members provide valid styles for IlconControI::setDefaultStyle and for the 
constructor of the IlconControI (p. 784) class. 


classDefaultStyle 

Original default style for this class, which is IWindow:ivisible. 


static const Style Supported On: 

classDefaultStyle; PM. Motif 

_Sizes the window to the size of the icon passed in on the constructor. 


static const Style 
sizeToIcon; 


Supported On: 

PM. Motif 


Inherited Public Data 


IStatieText 

bottom 

halftone 

strikeout 

center 

halftonetd 

strikeoutld 

classDefaultStyle 

left 

top 

fillBackground 

limitld 

underscore 
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IStaticText 

fillBackgroundld 

mnemonic 

underscoreld 

fillColorld 

right 

vertCenter 


ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoIorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IlconControl contains the following nested classes: 
IlconControl ::Style (see page 792) 
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llconControl::Style 


IBase 

IBitFlag 

IlconControI:: Style 


_.None. 

—iiconctl.hpp 

The nested class IlconControI::Style provides a set of valid styles for the IlconControI 
(p. 784) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IlnfoArea 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IStaticText 

IlnfoArea 


_.None. 

__iinfoa.hpp 


Member 

Page 

Member 

Page 

Constructor 

794 

missingTextld 

801 

calcMinimumSize 

800 

resourceLibrary 

796 

disabledText 

796 

resourceLibraryld 

801 

disabledTextld 

801 

setDisabledText 

797 

dispatchHandlerEvent 

799 

setlnactiveText 

797 

handleEventsFor 

795 

setLineCount 

795 

inactiveText 

796 

setMissingText 

797 

inactiveTextld 

801 

setResourceLibrary 

796 

informationFor 

799 

setStringTableOffset 

798 

lineCount 

795 

stopHandlingEventsFor 

795 

menuEnded 

800 

stringTableOffset 

798 

menuSelected 

800 

“IlnfoArea 

795 

missingText 

797 




Objects of the IlnfoArea class provide a frame extension at the bottom of the client 
area. The frame extension shows information about the frame menu item at which 
the selection cursor is currently positioned. 

The information area displays the contents of an entry in a resource string table. The 
string resource is obtained by using the same ID as the menu item plus some optional 
offset value that is added to the menu item ID to locate the corresponding string of 
information about it. 

IPM The User Interface Class Library loads the strings from a dynamic link library 

(.DLL). You can specify a library name, or you can use 0 to indicate that the default 
user application resource library supplies the resources. 
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j ~~ The User Interface Class Library loads the strings from the user default library. 

Unlike OS/2 Presentation Manager, Motif does not update the information area for 
menu bar items (CascadeButtons). Only pull-down menu item (ToggleButton) 
information is presented by the information area. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IlnfoArea 
objects because both the copy constructor and assignment operator are private functions. 

IlnfoArea 

| IInfoArea( IFrameWindow* frame, 

const char* resDLLName, 
unsigned long id = 0); 

Use this constructor to create IlnfoArea objects from a pointer to a frame window, the 
name of the resource DLL, and the ID for the information area control, 

| IInfoArea( IFrameWindow* frame. Supported On: 

unsigned long id = 0); PM, Motif 

Use this constructor to construct an IlnfoArea object from a frame window pointer 
and an ID for the information area control. By default, the information strings will 
be loaded from the user default resource library obtained from userResourceLibrary. 

2 IInfoArea( IFrameWindow* frame. Supported On: 

unsigned long id, PM, Motif 

const char* resDLLName); 

Use this constructor to create IlnfoArea objects from a pointer to a frame window, an 
ID for the information area control, and the name of the resource DLL. 

2 IInfoArea( IFrameWindow* frame, 

const IModuleHandle& resMod, 
unsigned 1ong id = 0); 

Use this constructor to create IlnfoArea objects from a pointer to a frame window, a 
module handle of the resource DLL, and an ID for the information area control. If 
the module handle is 0, the information strings are loaded from the current .EXE. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


794 


Open Class Library Reference 



IlnfoArea 


I Info Area 


virtual 

'IlnfoAreaO; 


Supported On: 

PM, Motif 


Display Size 

Use these members to control the height of the information area's minimum size, in terms of 
lines of text. By default, the frame uses this to size the height of this frame extension. 

_ Returns the number of text lines that the information area uses. 

virtual unsigned long Supported On: 

lineCount() const; PM 

... Sets the number of text lines that the information area uses to display text. The 
default is 1 line. 

virtual IInfoArea& Supported On: 

setLineCount( unsigned long lines = 1); PM 


Exceptions 

IlnvalidParameter The number of lines specified must be greater than 0. 


Event Dispatching 

Use these members to attach the handler of the information area to and detach it from a frame 
window. These members are used when adding the information area extension to the frame 
window, so you should not have to call them. 

handleEventsFor 

Attaches the handler of the information area to the specified frame window. 

virtual IInfoArea& Supported On: 

handleEventsFor( IFrameWindow* frame); PM, Motif 


Exceptions 

IlnvalidParameter An invalid frame window pointer was specified. You must specify a valid 

IFrameWindow pointer. 


stopHandlingEventsFor 

Detaches the handler of the information area from the specified frame window. 
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virtual IInfoArea& 

stopHandlingEventsFor( IFrameWindow* frame); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter An invalid frame window pointer was specified. You must specify a valid 

IFrameWindow pointer. 


Resource Library 

Use these members to query and set the resource library from which the information strings are 
to be loaded. 


resourceLibrary 

Returns a reference to the library being used. 


virtual IResourceLibrary& Supported On: 

resourceLibrary() const; PM. Motif 

setResourceLibrary 

Sets the specified resource library. 

[J virtual IInfoArea& Supported On: 

setResourceLibrary( const char* resDLLName); PM, Motif Ignored 

Use this function to set the resource library using the name of a .DLL file. 

g virtual IInfoArea& Supported On: 

setResourceLibrary( const IModuleHandl e& resMod); PM. Motif Ignored 

Use this function to set the resource library using a module handle. 

Special Information Strings 

Use these members to set and query the value of the information strings displayed in special 
circumstances. Special circumstances include when the menu is inactive, when a disabled menu 
item is the current menu item, or when the text for the selected menu item is missing. Each 
special string can be specified as either an IString or the identifier for a string from the resource 
library. 


__Returns the text displayed when the menu item at the selection cursor is disabled. 

virtual IString Supported On: 

disabledText() const; PM. Motif 

—Returns the text displayed when the menu is inactive. 
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virtual IString Supported On: 

inactiveText() const; PM, Motif 

_ Returns the text that displays when the User Interface Class Library cannot obtain 
the required information string from the resource library. 


virtual IString 
missingText() const; 


Supported On: 

PM, Motif 


setDisabledText 

Sets the text that is displayed whenever a disabled menu item becomes the current 
menu item. To display the text, you must call this function before the disabled menu 
item is made the current menu item. Otherwise, the normal information area text is 
displayed. 


2 virtual IInfoArea& 

setDisabledText( const IString& disabledText); 


Supported On: 

PM, Motif 


£ virtual IInfoArea& 

setDisabledText( unsigned long disabledText); 


Supported On: 

PM, Motif 


setlnactiveText 

Sets the text that is used when the menu is inactive. 


Q virtual IInfoArea& 

setlnactivefext( unsigned long inactiveText); 


Supported On: 

PM, Motif 


§ virtual IInfoArea& Supported On: 

setInactiveText( const IString& inactiveText); PM, Motif 

setMissingText 

Sets the text that displays when the User Interface Class Library cannot find the 
information string. 

Q virtual IInfoArea& Supported On: 

setMissingText( unsigned long missingText); PM, Motif 


£ virtual IInfoArea& 

setMissingText( const IString& missingText); 


Supported On: 

PM, Motif 
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String Table Offset 

Use these members to set and query the string table offset. The string table offset is added to the 
menu identifier to obtain the identifier for the string providing the information about the menu 
item. The default is zero. 

setStringTableOffset 

Sets the offset to be used to calculate the information string ID. 


virtual IInfoArea& Supported On: 

setStringTableOffset( long newOffset = 0); PM. Motif 

stringTableOffset 

Returns the offset currently in use. 


virtual long 

stringTableOffset() const; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IStatieText 

alignment 

enableFillBackground 

isStrikeout 

backgroundColor 

enableHalftone 

isUnderscore 

convertToGUIStyle 

enableS trikeout 

limit 

defaultStyle 

enableUnderscore 

moveSizeTo 

disableFillBackground 

fiUColor 

resetFillColor 

disableHalftone 

foregroundColor 

setAlignment 

disableStrikeout 

hasFillBackground 

setDefaultStyle 

disableUnderscore 

isHalftone 

setFillColor 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 
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INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Event Dispatching 

Use these members to attach the handler of the information area to and detach it from a frame 
window. These members are used when adding the information area extension to the frame 
window, so you should not have to call them. 

dispatchHandlerEvent 

Calls the appropriate virtual function or functions to process an information area 
event. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


Information String Processing 

These members implement this class. Derived classes can override them to tailor the behavior. 


informationFor 

Returns the information string for the specified menu ID. 


virtual IString 

informationFor( unsigned long menuld) const; 


Supported On: 

PM, Motif 


Layout Support 

Layout is information used by the canvas classes to provide dialog-like behavior. 
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calcMinimumSize 

Returns the minimum size of the information area, based on the number of text lines 
that the information area displays and the text limit. The default text limit is 80. 

virtual ISize Supported On: 

calcMinimumSize() const; PM 


Menu Event Processing 

These members are overridden from class IMenuHandler to handle the menu events 
appropriately. 

^Places the inactive information string into the information area. 


virtual Boolean 

menuEnded( IMenuEvent& menuEvent); 


Supported On: 

PM. Motif 


menuSelected 

Places the corresponding information string into the information area. 


virtual Boolean 

menuSelected( IMenuEvent& menuEvent); 


Supported On: 

PM. Motif 


Inherited Protected Functions 


IStatieText 

calcLimitSize 

calcMinimumSize 

passEventToOwner 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 

Notification Members 

These INotificationld strings are used for all notifications that IlnfoArea provides to its observers. 
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disabledTextld 

Notification identifier provided to observers when the disabled text of the info area 
control changes. IlnfoArea provides a pointer to the new text string in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

disabledTextld; PM, Motif 


inactiveTextld 

Notification identifier provided to observers when the inactive text of the info area 
control changes. IlnfoArea provides a pointer to the new text string in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

inactiveTextld; PM, Motif 

missingTextld 

Notification identifier provided to observers when the missing text of the info area 
control changes. IlnfoArea provides a pointer to the new text string in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

missingTextld; PM, Motif 

resourceLibraryld 

Notification identifier provided to observers when the resource library of the info area 
control changes. IlnfoArea provides a pointer to the new resource library in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 


static INotificationld const 
resourcel-i braryld; 


Supported On: 

PM, Motif 


Inherited Public Data 


IStaticText 

bottom 

halftone 

strikeout 

center 

halftoneld 

strikeoutld 

classDefaultStyle 

left 

top 

fillBackground 

limitld 

underscore 
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IlnfoArea 


IStaticText 

fillBackgroundld 

mnemonic 

underscoreld 

fillColorld 

right 

vertCenter 


ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderCoiorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



802 Open Class Library Reference 






IMM24F ramesPerSecondT ime 



IMM24FramesPerSecondTime 


IBase 

IVBase 

IMMTime 

IMMHourMinSecFrameTime 

IMM24FramesPerSecondTime 


_.None. 

_dmrntime.hpp 


Member Page 

Constructor 803 

operator unsigned long 804 

“IMM24FramesPerSecondTime 804 


The IMM24FramesPerSecondTime data type class represents the frame-numbering 
system that assigns a number to each frame of video. This system was developed by 
the Society of Motion Picture and Television Engineers. The 8-digit code is in the 
form HH:MM:SS.FF (hours, minutes, seconds, frame number). The numbers track 
elapsed hours, minutes, seconds, and frames from any chosen point. This time format 
is based on 24 frames per second. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMM24FramesPerSecondTime 

Q IMM24FramesPerSecondTime( Supported On: 

unsigned long value = defaul tTime); PM 

You can construct an IMM24FramesPerSecondTime from the following parameter 
variable: 
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IMM24F ramesPerSecondT ime 


value A time value where: 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

g IMM24FramesPerSecondTime( Supported On: 

const IMM24FramesPerSecondTime& time); PM 

IMM24FramesPerSecondTime 

virtual Supported On: 

'IMM24FramesPerSecondTime(); PM 


Conversions 

Use these members to cast the time to an unsigned long. 

_Returns the time as a unsigned long in the following format (FFSSMMHH): 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

virtual Supported On: 

operator unsigned 1 ong() const; PM 


Inherited Public Functions 


IMMHourMinSecFrameTime 

asString 

hours 

ordinal 

frames 

minutes 

seconds 

framesPerSecond 

operator unsigned long 

setTimeToOrdinal 


IMMTime 

asMMTime 

operator + 

operator == 

asString 

operator += 

operator > 

hours 

operator - 

operator >= 
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IMMTime 

hundredths 

operator -= 

operator unsigned long 

is Valid 

operator < 

ordinal 

minutes 

operator <= 

seconds 

operator != 

operator = 

setTimeToOrdinal 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMTime 

setMMTime 

set Valid 



Inherited Public Data 


IMMTime 

defaultTime 




Inherited Protected Data 


I Base 

recoverable 

unrecoverable 
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IMM25F ramesPerSecondT ime 



IMM25FramesPerSecondTime 


IBase 

IVBase 

IMMTime 

IMMHourMinS ecFrameT ime 
IMM25FramesPerSecondTime 


_.None. 


—immtime.hpp 


Member 

Page 

Constructor 

806 

operator unsigned long 

807 

~IMM25FramesPerSecondTime 

807 


IMM25FramesPerSecondTime data type class represents the frame-numbering system 
that assigns a number to each frame of video. This system was developed by the 
Society of Motion Picture and Television Engineers. The 8-digit code is in the form 
HH:MM:SS.FF (hours, minutes, seconds, frame number). The numbers track elapsed 
hours, minutes, seconds, and frames from any chosen point. This time format is 
based on 25 frames per second. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMM25FramesPerSecondTime 

[] IMM25FramesPerSecondTime( Supported On: 

unsigned long value = defaultTime); PM 

You can construct an IMM25FramesPerSecondTime from the following parameter 
variable: 
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IMM25F ramesPerSecondT ime 


value A time value where: 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

§ IMM25FramesPerSecondTime( Supported On: 

const IMM25FramesPerSecondTime& time); PM 

IMM25FramesPerSecondTime 

virtual Supported On: 

UMM25FramesPerSecondTime(); PM 


Conversions 

Use these members to cast the time to an unsigned long. 

_Returns the time as a unsigned long in the following format (FFSSMMHH): 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

virtual Supported On: 

operator unsigned long() const; PM 


Inherited Public Functions 


IMMHourMinSecF rameTime 

asString 

hours 

ordinal 

frames 

minutes 

seconds 

framesPerSecond 

operator unsigned long 

setTimeToOrdinal 


IMMTime 

asMMTirae 

operator + 

operator == 

asString 

operator += 

operator > 

hours 

operator - 

operator >= 
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IMMTime 

hundredths 

operator -= 

operator unsigned long 

is Valid 

operator < 

ordinal 

minutes 

operator <= 

seconds 

operator != 

operator = 

setTimeToOrdinal 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMTime 

setMMTime 

setValid 



Inherited Public Data 


IMMTime 

defaultTime 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMM30FramesPerSecondTime 


IBase 

IVBase 

IMMTime 

IMMHourMinSecFrameTime 

IMM30FramesPerSecondTime 


_.None. 

_Jmrntime.hpp 


Member Page 

Constructor 809 

operator unsigned long 810 

'IMM30FramesPerSecondTime 810 


The IMM30FramesPerSecondTime data type class represents the frame-numbering 
system that assigns a number to each frame of video. This system was developed by 
the Society of Motion Picture and Television Engineers. The 8-digit code is in the 
form HH:MM:SS.FF (hours, minutes, seconds, frame number). The numbers track 
elapsed hours, minutes, seconds, and frames from any chosen point. This time format 
is based on 30 frames per second. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMM30FramesPerSecondTime 

Q IMM30FramesPerSecondTime( Supported On: 

unsigned long value = defaul tTime); PM 

You can construct an IMM30FramesPerSecondTime from the following parameter 
variable: 
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value A time value where: 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

g IMM30FramesPerSecondTime( Supported On: 

const IMM30FramesPerSecondTime& time); PM 

~IMM30FramesPerSecondTime 

virtual Supported On: 

'IMM3QFramesPerSecondTime(); PM 


Conversions 

Use these members to cast the time to an unsigned long. 

_Returns the time as a unsigned long in the following format (FFSSMMHH): 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

virtual Supported On: 

operator unsigned 1 ong() const; PM 


Inherited Public Functions 


IMMHourMinSecFrameTime 

asString 

hours 

ordinal 

frames 

minutes 

seconds 

framesPerSecond 

operator unsigned long 

setTimeToOrdinal 


IMMTime 

asMMTime 

operator + 

operator == 

asString 

operator += 

operator > 

hours 

operator - 

operator >= 
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IMMTime 

hundredths 

operator -= 

operator unsigned long 

is Valid 

operator < 

ordinal 

minutes 

operator <= 

seconds 

operator != 

operator = 

setTimeToOrdinal 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMTime 

setMMTime 

set Valid 



Inherited Public Data 


IMMTime 

defaultTime 




Inherited Protected Data 


I Base 

recoverable 

unrecoverable 
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IMMAmpMixer 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMAmpMixer 


_.None. 


Mmmamix.hpp 

Member 

Page 

Constructor 

812 

balance 

813 

bass 

814 

disableMonitoring 

817 

enableMonitoring 

817 

gain 

814 

isMonitoringEnabled 

818 

isOpenStringV alid 

819 


Member 

Page 

pitch 

814 

setBalance 

815 

setBass 

815 

setGain 

815 

setPitch 

816 

setTreble 

816 

treble 

816 

'IMMAmpMixer 

813 


The IMMAmpMixer class provides input or output switching and sound-shaping 
services, such as volume, treble, gain, or bass control. The amplifier-mixer is similar 
to a home stereo amplifier and mixer. Devices are connected to the IMMAmpMixer 
so that audio signals can be transferred to speakers or another device. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMAmpMixer 

[] IMMAmpMixer( Boolean openNow = true, Supported On: 

unsigned long instance = 0, PM 

Boolean openShareable = true); 
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IMMAmpMixer 


You can construct an IMMAmpMixer from the following: 

openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 

instance Specifes your own instance number instead of one being generated for 
you. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 

§ IMMAmpMixer( unsigned long deviceldentifier. Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMAmpMixer from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


IMMAmpMixer 


virtual 

'IMMAmpMixerO ; 


Supported On: 

PM 


Mixer Attributes 

Use these members to query and set the different amplifier-mixer attributes. 

Returns the balance, where 0 is defined as full left balance and 100 is defined as full 
right balance. 

unsigned long Supported On: 

balance( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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Returns the bass, where 0% is the least amount of bass and 100% is the most 
amount of bass. 

unsigned long Supported On: 

bass( Call Type call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Returns the gain, where 0% is the least amount of gain and 100% is the most 
amount of gain.. 


unsigned long 
gain( CallType cal 

Supported On: 

1 = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Returns the pitch, where 0 is the lowest pitch and 100 the highest pitch. 

unsigned long Supported On: 

pitch( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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_Sets the balance, where 0 is defined as full left balance and 100 is defined as full 
right balance. 


virtual IMMAmpMixer& 

setBalance( unsigned long balance. 
Cal Hype cal 1 = wai t); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


.Sets the bass, where 0% is the least amount of bass and 100% is the most amount of 

bass. 


virtual IMMAmpMixer& 

setBass( unsigned long bass. 

Cal 1 Type cal 1 = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

...Sets the gain, 
gain. 

where 0% is the least amount of gain and 100% is the most amount of 

virtual IMMAmpMixer& Supported On: 

setGain( unsigned long gain, PM 

Cal 1 Type cal 1 = wai t); 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 
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Exceptions 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

... Sets the pitch, where 

0 is lowest pitch and 100 is the highest pitch. 

virtual IMMAmpMixer& 
setPitch( unsigned 
CallType 

Supported On: 

long pitch, PM 

cal 1 = wait); 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

.Sets the treble, where 

treble. 

0 is the least amount of treble and 100 is the most amount of 

virtual IMMAmpMixer& 
setTreble( unsigned 
Cal 1 Type 

Supported On: 

long treble, PM 

cal 1 = wait); 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Returns the treble, where 0 is the least amount of treble and 100 is the most amount 
of treble. 

unsigned long Supported On: 

treble( CallType call = wait) const; PM 
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Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Monitoring 

Use these members to either allow or not allow the signal from an input device to be heard when 
it is being routed to another device. 

The amplifier-mixer device has the ability to monitor (listen to) the audio signal from one device 
while the audio signal from a second device is being recorded. The main use of monitoring is 
for recording and mixing more than one audio source. The amplifier-mixer device supports one 
audio connection and the ability to monitor a second audio source. 

disableMonitoring 

Does not allow the signal from an input device to be heard as it is being routed to 
another device. The amplifier-mixer device has the ability to monitor (listen to) the 
audio signal from one device while the audio signal from a second device is being 
recorded. The main use of monitoring is for recording and mixing more than one 
audio source. The amplifier-mixer device supports one audio connection and the 
ability to monitor a second audio source. 


virtual IMMAmpMixer& Supported On: 

disableMonitoring( Call Type call = wait); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


enableMonitoring 

Allows the signal from an input device to be heard as it is being routed to another 
device. The amplifier-mixer device has the ability to monitor (listen to) the audio 
signal from one device while the audio signal from a second device is being recorded. 
The main use of monitoring is for recording and mixing more than one audio source. 
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The amplifier-mixer device supports one audio connection and the ability to monitor a 
second audio source. 


virtual IMMAmpMixer& 
enableMonitoring( Boolean enable = true. 
Cal 1 Type cal 1 = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


isMonitoringEnabled 

Returns true if the monitor is turned on. The amplifier-mixer device has the ability to 
monitor (listen to) the audio signal from one device while the audio signal from a 
second device is being recorded. 


Bool ean Supported On: 

isMonitoringEnabled( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Inherited Public Functions 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 


818 Open Class Library Reference 







IMMAmpMixer 


IMMDevice 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports V olume Adj ustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Implementation 

These members check if the passed in string is in the correct format to open the current device. 


isOpenStringValid 

Returns true if the passed in open string is valid for this device. 


virtual Boolean 

isOpenStringValid( const IString& deviceName) const; 


Supported On: 

PM 
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Inherited Protected Functions 


IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Inherited Public Data 


IMMDevice 

allDevices 

euePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digitalVideo 

positionChangeld 

audioTape 

headphone 

sequencer 

cdxa 

microphone 

speaker 

commandNotifyld 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMAudioBuffer 


IBase 

IMMAudioBuffer 


_.None. 


_Jmmahuf.hpp 


Member 

Page 

Member 

Page 

Constructor 

824 

operator = 

824 

audio 

826 

samplesPerSecond 

822 

bitsPerS ample 

822 

setB itsPerS ample 

822 

blockAlignment 

822 

setB lockAlignment 

823 

bytesPerSecond 

822 

setB y te sPerS econd 

823 

channels 

822 

setChannels 

823 

contentType 

825 

setContentType 

825 

data 

823 

setData 

824 

format 

825 

setFormat 

825 

headerData 

823 

setMediaType 

826 

length 

823 

setS ample sPerSecond 

823 

mediaType 

825 

~IMM AudioB uffer 

825 


The IMMAudioBuffer class provides a buffering mechanism that allows device 
classes to operate on a buffer as if it were a file. It is recommended that you set up 
the type and format of audio data that is to be recorded or playing. Using buffers 
improves the performance of multimedia applications that perform numerous file 
input and output operations when accessing media devices. You might want to use a 
buffer for applications that perform many input and output operations that are less 
than 4KB each. However, if your operations are larger than 4KB, then you might not 
want to use a buffer. In this situation, you will see little to no performance gain. 

You might have performance degregation, since it will have to copy data in big 
blocks at a time. 


Public Functions 
Audio Attributes 

Use these members to query and set the audio attributes for the audio buffer. 
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bitsPerSample 

Returns the number of bits-per-sample. This is the number of bits of data used to 
represent each sample of each channel. The standard values are 4, 8, and 16. 

unsigned long Supported On: 

bitsPerSample() const; PM 


blockAlignment 

Returns the block alignment of data in bytes. The system processes a multiple of 
block aligned bytes of data at a time. For example, if you have a 24-byte buffer, then 
you can only set a block alignment of 2, 3, 4, 6, 8, or 12. 

unsigned long Supported On: 

bl ockAl ignment () const; PM 


bytes PerSecond 

Returns the average number of bytes-per-second played or recorded. This is the rate 
the data is transferred to the hardware. 

unsigned long Supported On: 

bytesPerSecond() const; PM 

-Returns the number of audio channels set. For example, mono is 1; stereo is 2. 

unsigned long Supported On: 

channels() const; PM 

samplesPerSecond 

Returns the number of samples-per-second played or recorded. This is the sampling 
rate, in kilohertz, which each channel should use. Standard values are 11025, 22050, 
and 44100. 


unsigned long Supported On: 

samplesPerSecond() const; PM 


setBitsPerSample 

Sets the bits-per-sample to be played or recorded. This is the number of bits of data 
used to represent each sample of each channel. The standard values are 4, 8, and 16. 

IMMAudioBuffer& Supported On: 

setBitsPerSample( unsigned long bitsPerSample); PM 
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setBlockAlignment 

Sets the block alignment of the data. The system processes a multiple of block 
aligned bytes of data at a time. For example, if you have a 24-byte buffer, then you 
can only set a block alignment of 2, 3, 4, 6, 8, or 12. 

IMMAudioBuffer& 

setBlockAlignment( unsigned long alignment); 

setBytesPerSecond 

Sets the average bytes per second to be played or recorded. This is the rate the data 
is transferred to the hardware. 

IMMAudioBuffer& Supported On: 

setBytesPerSecond( unsigned long averageBytes); PM 

_.Sets the number of audio channels for playing and recording. Monaural is 1; stereo 
is 2. 


IMMAudioBuffer& 

setChannels( unsigned long channels); 

setSamplesPerSecond 

Sets the samples rate for playing and recording. This is the sampling rate, in 
kilohertz, which each channel should use. Standard values are 11025, 22050, and 
44100. 

IMMAudioBuffer& Supported On: 

setSamplesPerSecond( unsigned long samplesPerSecond); PM 


Supported On: 

PM 


Supported On: 

PM 


Buffer Management 

Use these members to query and set the buffer data and to query the length of the buffer. 
Returns an IString that contains a copy of the data in the audio buffer. 

IString Supported On: 

data() const; PM 

-.Returns an IString that contains the operating system specific header information. 

IString Supported On: 

headerData() const; PM 

Returns the size of the buffer. 
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unsigned long Supported On: 

length() const; PM 

.Sets the contains and size of the audio buffer to that of the passed in buffer. 


IMMAudioBuffer& 
setData( const void* data, 

unsigned long dataLength); 


Supported On: 

PM 


Constructors 

You can construct, copy, and destruct objects of this class. 


IMMAudioBuffer 


[J IMMAudi oBuffer( const IMMAudioBuffer& audioBuffer) ; Supported On: 

PM 


| IMMAudioBuffer( void* audioData, Supported On: 

unsigned long dataLength); PM 

You can construct an IMMAudioBuffer from: 

audioData The audio buffer is initialized with the data from the passed in buffer. 
dataLength 

The length of the passed in buffer, which is the size of the audio buffer. 


0 IMMAudioBuffer( unsigned long dataLength = 0); Supported On: 

PM 

You can construct an IMMAudioBuffer from the following: 
dataLength 

The size of the audio buffer to be created. It is initalized with all 0's. 

_ Copies the audio buffer information from the passed in audio buffer. 

IMMAudioBuffer& Supported On: 

operator =( const IMMAudioBuffer& audioBuffer); PM 
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_ IMMAudioBuffer(); Supported On: 

PM 


Content Type 

Use these members to set and query the quality of the audio content. 

_ Returns the audio content type. 

ContentType Supported On: 

contentType() const; PM 

setContentType 

Sets the audio content type. 

IMMAudioBuffer& Supported On: 

setContentType( ContentType contentType); PM 

Format 

Use these members to set and query the format of the audio data. 

Returns the interpretation of the audio format. This is what format the audio data is 
in. 


Format Supported On: 

format() const; PM 

... Sets the audio format to be used. This determines what format the audio data is in. 


IMMAudioBuffer& 
setFormat( Format tag = pern); 


Supported On: 

PM 


Media Type 

Use these members to query and set the type of media in the buffer. 

_ Returns the type of multimedia data in the buffer. 

unsigned long Supported On: 

mediaType() const; PM 
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setMediaType 

Sets the type of multimedia data in the buffer. 

IMMAudioBuffer& Supported On: 

setMediaType( unsigned long media = audio); PM 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 
Media Type 

Use these members to query and set the type of media in the buffer. 
Represents audio data. 


static const unsigned long 
audio; 

Supported On: 

PM 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 



ContentType { 
Unknown, 
Voice, 

Music, 

HiFi = 0x0004 

1 ; 


Use this enumeration for determining the quality of the audio content. Valid values 
are the following: 

unknown 

Represents unknown audio quality. 
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voice 

Represents voice (limited range) quality. 

music 

Represents FM radio or equivalent quality. 

hifi 

Represents high quality. 


Format { 




pcm = 0x0001, 

adpcm. 

ibmcvsd = 0x0005, 

al aw. 

mulaw. 

oki adpcm 

= 0x0010, dviadpcm, 

digistd = 0x0015 

digi fix, 

ctadpcm = 0x0200 

ibmmulaw 

= 0x0101, ibmalaw. 

avcadpcm. 


}; 


Use this enumeration for determining how audio information is stored and interpreted. 
The pcm format is the most commonly used format. Valid values are the following: 

pcm 

Represents pulse code modulation. This refers to a variation of a digital signal 
to represent audio amplitude. This method of assigning binary values to 
amplitude levels supports the conversion of analog signals to digital signals by 
sound cards. 

adpcm 

Represents adaptive differential pulse code modulation. This is a technique for 
compressing waveform samples. It can reduce the amount of data storage 
required by a factor of 16 to 1, but some price is paid in fidelity for the higher 
compression rates. 

ibmcvsd 

Represents the IBM Speech Viewer format. 

alaw 

Represents the CCITT A-Law format. 

mulaw 

Represents the CCITT MuLaw format. 

okiadpcm 

Represents the OKI adaptive pulse code modulation format. 

dviadpcm 

Represents the DVI adaptive pulse code modulation format. 

digistd 

Represents the IBM Digispeech standard format. 
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digifix 

Represents the IBM Digispeech fixed format. 

ibmmulaw 

Represents the IBM MuLaw format. 

ibmalaw 

Represents the IBM A-Law format. 

avcadpcm 

Represents IBM AVC adaptive differential pulse code modulation format. 

ctadpcm 

Represents the Creative Labs adaptive differential pulse code modulation 
format. 
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IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMRemovableMedia 

IMMAudioCD 


_.None. 

_Jmmcdda.hpp 


Member 
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Member 
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The IMMAudioCD class is the audio compact disc (CD) class and provides behavior 
for CD audio players. Most people are familiar with a home or car CD player. So, 
just like a normal CD player, there are functions for play, pause, stop, trackForward, 
trackBackward, scanning, and so on. Plus, there are some additional features, for 
example, rearranging the playback order for tracks and storing track and disc titles. 
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Public Functions 
Compact Disc Information 

Use these members to query of information and states for the CD audio device and the loaded 
compact disc. For example, you can query and set autoPlay and continuousPlay, and you can 
query the number of tracks, the disc title, the disc identifier, and the universal product code(upc). 

disableAutoPlay 

Sets autoplay off. Autoplay causes the CD audio device to start playing whenever a 
CD is loaded. 

IMMAudioCD& 
di sabl eAutoPl ay (); 

disableContinuousPlay 

Sets continuous play off. If the continuous play is set, then the current track is 
repeated continuously on playback. 


Supported On: 

PM 


IMMAudioCD& Supported On: 

di sabl eContinuousPl ay (); PM 

Returns the identifier of the current disc. If there is no identifier on the CD then it 
returns a null IString. 


IString 

disc Id( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


Returns the disc title. A null IString is returned if you have not set a title. 


IString Supported On: 

discTitle() const; PM 
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Exceptions 

IlnvalidRequest 

There must be media present in the device. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


enableAutoPlay 

Turns autoplay on or off. Autoplay causes the audio CD device to start playing 
whenever a CD is loaded. 

IMMAudioCD& 

enableAutoPlay( Boolean autoPlay = true); 

enableContinuousPlay 

Turns continuous play on or off. If the continuous play is set, then the current track 
is repeated continuously on playback. 


Supported On: 

PM 


IMMAudioCD& Supported On: 

enableContinuousPlay( Boolean continuousPlay = true); PM 

isAutoPlayEnabled 

Returns true, if autoplay is turned on. Autoplay causes the audio CD device to start 
playing whenever a CD is loaded. 

Boolean 

isAutoPlayEnabled() const; 

isContinuousPlayEnabled 

Returns true, if continuous play is turned on. If the continuous play is set, then the 
current track is repeated continuously on playback. 

Boolean Supported On: 

isContinuousPlayEnabled() const; PM 


Supported On: 

PM 


numberOfTracks 

Returns the number of tracks. 

unsigned long Supported On: 

numberOfTracks( CallType call = wait) const; PM 

_.Sets the disc's title. The disc title is stored in the currently set profile. See 
setProfile (p. 839) for more information on profiles. 
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IMMAudioCD& 

Supported On: 

setDiscTitle( const 

IStri ng& ti tl e); 

PM 

Exceptions 

IlnvalidRequest 

There must be media present in the device. 


IlnvalidRequest 

The device must be in the open state before calling this function. 



__Sets the track's title. The track title is stored in the currently set profile. See 
setProfile (p. 839) for more information on profiles. 


IMMAudioCD& Supported On: 

setTrackTi tl e( const IString& title, PM 

unsigned 1ong track); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


.Returns the track title. A null IString is returned if you have not set a title for the 

passed in track. 


IString 

trackTitle( unsigned long track) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


Returns the disc's universal product code (serial number). If the disc does not 
contain a upc, then a null IString is returned. 
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IString 

upc( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


Constructors 

You can construct and destruct objects of this class. 


IMMAudioCD 


IMMAudioCD( IProfile* profile = 0, 

Boolean openNow = true, 
unsigned long instance = 0, 

Boolean openShareable = true); 

You can construct an IMMAudioCD from the following: 

profile You can provide your own profile where information can be retrieved and 
stored from. Some of the information stored in a profile is disc titles and 
the IMMAudioCDContents for different CDs. If you pass in 0, then the 
device uses the system profile for storing and retrieving information. 

openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 

instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 


Supported On: 

PM 
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virtual Supported On: 

'IMMAudioCD(); PM 

Play, Stop, and Scan 

Use these members to stop playing or scanning, start scanning or playing, resume or pause the 
playback, or move the current position to a new location. 

_Moves the current position to the passed in location. This location is a track 
number and the time into the track. 

[J virtual IMMAudioCD& Supported On: 

goToEntry( unsigned long index); PM 

It retrieves this information out of the currently set program at the passed in index. If 
you passed in 3, it looks up the track number in the current program at that location. 

If you have not set your own program then the default program is used. This 
program is a straight mapping of the tracks, for example, at index 3, track number 3 
is stored. You can set your own program. For example, you could have the 
following: at index 1, track 5; at index 2, track 4; and at index 3, track 6. If you 
passed in index 3, this function moves the current position to track number 6. 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


g virtual IMMAudioCD& Supported On: 

goToEntry( IMMAudioCDContents: :Cursor cursor); PM 

It retrieves this information out of the currently set program at the passed in cursor. 

If you passed in a cursor that points to index 3, it looks up the track number in the 
current program at that location. If you have not set your own program then the 
default program is used. This program is a straight mapping of the tracks, for 
example, at index 3, track number 3 is stored. You can set your own program. For 
example, you could have the following: at index 1, track 5; at index 2, track 4; and 
at index 3, track 6. If you passed in a cursor that points to index 3, this function 
moves the current position to track number 6. 

834 Open Class Library Reference 




IMMAudioCD 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 

Pauses the audio CD device, if the audio CD device is playing. 

virtual IMMAudioCD& 

Supported On: 

pause ( Call Type call = wait); PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


.Starts playing the CD device from the passed in start position to the passed in end 
position. If from is omitted, the CD device starts playing at the current position; if to 
is omitted, play stops at the end of the disc. If the resumelfPaused Boolean is true 
and the CD player is paused, it resumes playing at the current location; otherwise, it 
starts playing at the passed in from location. 


virtual IMMAudioCD& Supported On: 

play( const IMMTime& from = IMMTime ( ), PM 

const IMMTime& to = IMMTime ( ), 

Boolean resumelfPaused = true, 

Call Type call = nowait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 
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Exceptions 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the contents of 
the CD. 

Resumes playback of the compact disc from a paused state. The previous specified 
to parameter in the play (p. 835) function remains in effect. 

virtual IMMAudioCD& 

Supported On: 

resume( Boolean resume = true, PM 

Cal 1 Type 

cal 1 = wait); 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


startscanning Backward 

Causes the audio CD device to search backward at high speed. If the device is 
currently scanning backward, this function has no effect, but, if the device is currently 
scanning forward, this causes the scanning to stop and to start scanning backward. 

You can stop the scanning by calling the stop (p. 837) function, or, if the CD was 
playing when scanning started, the play function stops the scanning and resumes 
playback at the new location. The scanning wraps to the end when it reaches the 
beginning of the compact disc. 


IMMAudioCD& Supported On: 

startScanningBackward(); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 
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Exceptions 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


startScanningForward 

Causes the audio CD device to search forward at high speed. If the device is 
currently scanning forward, this function has no effect, but, if the device is currently 
scanning backward, this causes the scanning to stop and to start scanning forward. 
You can stop the scanning by calling the stop (p. 837) function, or, if the CD was 
playing when scanning started, the play function stops the scanning and resumes 
playback at the new location. The scanning wraps to the beginning when it reaches 
the end of the compact disc. 


IMMAudioCD& 

startScanningForward(); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


Stops playback and backward or forward scanning of the compact disc. 

virtual IMMAudioCD& Supported On: 

stop( CallType call = wait); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 
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trackBackward 

Moves the current position backwards the passed in number of tracks. If the device 
was playing, it starts playing at the new position. 


IMMAudioCD& Supported On: 

trackBackward( unsigned long decrement = 1); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 


IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


.Move the current position forwards the passed in number of tracks. 

was playing, it starts playing at the new position. 

If the device 

IMMAudioCD& 

trackForward( unsigned long increment = 1); 

Supported On: 

PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 


IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 



Profile and Program 

Use these members to change and query the profile and program. 

Returns a copy of the CD's table of contents. 

IMMAudioCDContents Supported On: 

contents() const; PM 

Returns the current profile. The profile contains one or more compact disc titles and 
their IMMAudioCDContents. This can be useful if you want to retain a table of 
contents for one or more compact discs. For example, you might have a demo CD 
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that you want to play the third track first, followed by the second, and so on. You 
would not want to have to rearrange the tracks every time you loaded that CD. By 
storing the information in a profile, the IMMAudioCD class can load that disc's 
information from the profile so you do not have to reenter anything. 

I Prof i 1 e Supported On: 

profile() const; PM 

-Sets a new profile. The profile contains one or more compact disc titles and their 
IMMAudioCDContents. This can be useful if you want to retain a table of contents 
for one or more compact discs. For example, you might have a demo CD that you 
want to play the third track first, followed by the second, and so on. You would not 
want to have to rearrange the tracks every time you loaded that CD. By storing the 
information in a profile, the IMMAudioCD class can load that disc's information from 
the profile so you do not have to reenter anything. 


IMMAudi oCD& Supported On: 

setProfile( IProfile& profile); PM 

—Sets a new table of contents. The table of contents is stored in the currently set 
profile. The IMMAudioCD class plays and scans the compact disc according to the 
current table of contents. This allows you create your own table of contents for the 
current disc. For instance, you might want to store your compact discs (title and 
table of contents) in a database. Then, when you insert a CD, you could query its ID 
and see if it is in your database. If so, then you could retrieve your table of contents 
and set it into the device so that it always plays back the same way. 


IMMAudioCD& Supported On: 

setProgram( const IMMAudioCDContents& program); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


Inherited Public Functions 
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IMMRemovableMedia 

closeDoor 

isMediaPresent 

lockDoor 


IMMPlayableDevice 

addCuePoint 

position 

seekToStart 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supports Save 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports V olume Adj ustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


INotifier 

disableNotification 

enableN otif ication 

isEnabledForNotification 


IVBase 


asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMAudioCD( unsigned long deviceidentifier, Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMAudioCD from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Implementation 

These members are overridden to provide additional processing. 

isOpenStringValid 

Returns true if the passed in open string is valid for this device. 

virtual Boolean Supported On: 

isOpenStringValid( const IString& deviceName) const; PM 

uniqueDiscldentifier 

Returns the unique disc identifier. This value is the name of this class plus the 
identifier of the disc. This can be useful to use in addition to the upc, because not all 
manufacturers put upc on their CDs. 

virtual IString 
uniqueDiscldentifier() const; 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 


Table 

Use these members to query the hard-coded table of contents stored on the compact disc. 

getTableFromDisc 

Generates a table of contents based on the hard-coded values stored on the compact 
disc. The only data stored on the compact disc are the tracks and their lengths. 


IMMAudi oCDContents Supported On: 

getTableFromDiscO; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There must be media present in the device. 
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Inherited Protected Functions 


IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Public Data 

Compact Disc Information 

Use these members to query of information and states for the CD audio device and the loaded 
compact disc. For example, you can query and set autoPlay and continuousPlay, and you can 
query the number of tracks, the disc title, the disc identifier, and the universal product code(upc). 

discProgramKey 

This is set to the text string "IMMAudioCDProgramTitle". This string is used as a 
key to query and retrieve information from a profile. 

static const IString Supported On: 

discProgramKey; PM 

.. This is set to the text string "IMMAudioCDDiscTitle". This string is used as a key 
to query and retrieve information from a profile. 

static const IString Supported On: 

discTitleKey; PM 
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Notification Event Descriptions 

These INotificationld strings are used for all notifications that IMMAudioCD provides to its 
observers. 

positionTimerld 

Notification identifier provided to observers as the position changes. IMMAudioCD 
provides a pointer to an IMMTrackMinSecFrameTime (p. 1035) in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value represents the current position of the CD. 

static const INotificationld Supported On: 

positionTimerld; PM 


trackStartedld 

Notification identifier provided to observers when the a new track is started. 
IMMAudioCD provides a pointer to an IMMTrackMinSecFrameTime (p. 1035) in the 
eventData field of the INotificationEvent (Vol. I). This value represents the current 
position of the CD. 

static const INotificationld Supported On: 

trackStartedld; PM 


Inherited Public Data 


IMMRemovableMedia 

mediaLoadedld 




IMMDevice 

allDevices 

cuePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digitalVideo 

positionChangeld 

audioTape 

headphone 

sequencer 

cdxa 

microphone 

speaker 

commandNotifyld 

monitor 

videoDisc 
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IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMAudioCDContents 


IBase 

IVBase 

IMMAudioCDContents 


_.None. 

Mmmcdda.hpp 
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The IMMAudioCDContents class is the class for an audio CD's table of contents. It 
allows you to keep a list of tracks. With this list you can rearrange the playback 
order of the tracks. For example, you could put track 5 at the first location, track 7 
next, and then track 1. 


Public Functions 
Constructors 

You can construct, copy and destruct objects of this class. 


IMMAudioCDContents 

Use this function to create an IMMAudioCDContents. 

IMMAudioCDContents( const IMMAudioCDContents& newToc); Supported On: 

PM 


You cannot create your own table of contents without asking for one from the 
IMMAudioCD class. 
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Sets the contents to be the same as another table of contents. 


IMMAudioCDContents& Supported On: 

operator =( const IMMAudioCDContents& newContents); PM 


"IMMAudioCDContents 


virtual 

'IMMAudioCDContents(); 


Entry Information 

Use these members to add, remove, and replace the track numbers in the table of contents. For 
example, you want to listen to all of the CD except track 2 and you want to listen to track 5 
played twice. To do this, you create a cursor on the table of contents. Then, you move the 
cursor to track 2 and call the remove entry function. Next, you move the cursor to track 5 and 
call the add entry function with 5 for the track number. 

addEntryAsFirst 

Adds the track number to the beginning of the playback list. 


IMMAudi oCDContents& Supported On: 

addEntryAsFirst( unsigned long trackNumber); PM 


Supported On: 

PM 


addEntryAsNext 

Adds the track number after the cursor in the playback list. 


IMMAudioCDContents& 

addEntryAsNext( unsigned long trackNumber, 
const Cursor& cursor); 


Supported On: 

PM 


numberOfEntries 

Returns the number of tracks in the playback list. 


unsigned long 
numberOfEntries() const; 


Supported On: 

PM 


removeEntryAt 

Removes the track number at the cursor from the playback list. 
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IMMAudioCDContents& Supported On: 

removeEntryAt( const Cursor& cursor); PM 


replaceEntryAt 

Replaces the track number at the cursor. 


IMMAudioCDContents& 

replaceEntryAt( unsigned long newTrackNumber, 
const Cursor& cursor); 


Supported On: 

PM 


Exceptions 

IlnvalidParameter 

The new track number can not be less than 1 or greater than the number of 


tracks. 

IlnvalidParameter 

The passed in cursor or this object is not valid. 

IlnvalidRequest 

An internal processing error occurred with the stored list of tracks. 


Track Information 

Use these members to query information about the entry at the given cursor for this table of 
contents. 


controllnformation 

Returns the track control information at the given cursor. This value cannot be set 
because it is set by the manufacturer of the CD. 

unsigned long Supported On: 

control Information( const Cursor& cursor) const; PM 

Returns the country at the given cursor. This value cannot be set because it is set 
by the manufacturer of the CD. 

unsigned long 

country( const Cursor& cursor) const; 

Returns the compact disc identifier. 

IString Supported On: 

discld() const; PM 

__ Returns the ending time (position) of the track. 


Supported On: 

PM 


IMMTime 

endOfTrack( const Cursor& cursor) const; 


Supported On: 

PM 
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Returns true if the table of contents is valid. 

Boolean Supported On: 

isValidQ const; PM 


numberOfTracks 

Returns the number of tracks. 


unsigned long Supported On: 

numberOfTracks() const; PM 

Returns the owner of the track at the given cursor. This value cannot be set because 
it is set by the manufacturer of the CD. 


unsigned long Supported On: 

owner( const Cursor& cursor) const; PM 

—Returns the serial number of the track at the given cursor. This value cannot be set 
because it is set by the manufacturer of the CD. 

unsigned long 

serialNumber( const Cursor& cursor) const; 

—Returns the starting time (position) of the track 

IMMTime 

startOfTrack( const Cursor& cursor) const; 

Returns the track number at the given cursor. 

unsigned long Supported On: 

track( const Cursor& cursor) const; PM 


Supported On: 

PM 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Constructors 

You can construct, copy and destruct objects of this class. 

.Use this function to create an IMMAudioCDContents. 

[J IMMAudioCDContents(); Supported On: 

PM 


This creates an invalid table of contents. 

g IMMAudioCDContents( void* newContents, Supported On: 

const IString& identifier, PM 

unsigned long tracks); 

This function takes the following parameters: 

newContents 

This is an pointer to a list of table of contents structures created by the 
operating system. 

identifier This is the unique disc identifier generated by IMMAudioCD. 

tracks This is the number of tracks to be in the playback list for the table of 

contents. The IMMAudioCDContents creates a default playback list for 
the tracks. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IMMAudioCDContents contains the following nested classes: 
IMMAudioCDContents::Cursor (see page 851) 
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IMMAudioCDContents::Cursor 


IBase 

IVBase 

IMMAudioCDContents:: Cursor 


_.None. 


.Jmmcdda.hpp 
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853 
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The IMMAudioCDContents::Cursor class creates and manages the cursor support of 
the table of contents. You can use a cursor to traverse through the list of tracks. 


Public Functions 
Constructors 

You can construct, copy and destruct objects of this class. 

.Use this function to create a IMMAudioCDContents::Cursor. 

| Cursor( const IMMAudioCDContents& contents); 

This function creates a cursor on the passed in table of contents. 

@ Cursor(); 


Supported On: 

PM 


Supported On: 


PM 

This function creates an invalid cursor object. You have to set this cursor object 
equal to a valid cursor in order to use it. 
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0 Cursor( const Cursor& cursor); Supported On: 

PM 

This function is the copy constructor. It takes another cursor and sets this cursor to 
be the same as the passed in cursor. 

_ Sets this cursor to be the same as the passed in cursor. 

Cursor& Supported On: 

operator =( const Cursor& newCursor); PM 

Cursor 


virtual 
"CursorO; 


Supported On: 

PM 


Cursor Validation and Cursor Movement 

Use these members to change the cursor position in the list and to check the validity of the 
current position. 

Returns the current index. 


unsigned long Supported On: 

aslndex() const; PM 

...Flags this cursor as invalid. 


virtual Cursor& Supported On: 

invalidate(); PM 

Returns true if the cursor is valid. 


Bool ean Supported On: 

isValid() const; PM 

_.Points to the next item in the table of contents. If no more items exist, this 
invalidates the cursor. 


virtual Cursor& Supported On: 

operator ++(); PM 

..Points to the previous item in the table of contents. If no previous items exist, this 
invalidates the cursor. 
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virtual Cursor& Supported On: 

operator — (); PM 

- Points to the table of contents item and validates the cursor. 


virtual Cursor& Supported On: 

setToFirst(); PM 

^Points to the item with the given 0-based index and validates the cursor. 


virtual Cursor& Supported On: 

setToIndex( unsigned long tolndex); PM 

-Points to the last table of contents item and validates the cursor. 


virtual Cursor& Supported On: 

setToLast(); PM 

.. Points to the next item in the table of contents. If no more items exist, this 
invalidates the cursor. 


virtual Cursor& 
setToNext(); 


Supported On: 

PM 


setToPrevious 

Points to the previous item in the table of contents. If no previous items exist, this 
invalidates the cursor. 


virtual Cursor& 
setToPrevious(); 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMCDXA 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMRemovableMedia 

IMMCDXA 


_.None. 


—immcdxa.hpp 
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The IMMCDXA class provides behavior for devices that support CD-ROM Extended 
Architecture(XA) discs. CD-XA refers to a storage format that accommodates 
interleaved storage of audio, video, and standard file data. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMCDXA 


IMMCDXA ( Boolean openNow = true. Supported On: 

unsigned long instance = 0, PM 

Boolean openShareable = true); 

You can construct an IMMCDXA from the following: 

openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 
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instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 


IMMCDXA 


virtual 
'IMMCDXA(); 


Supported On: 

PM 


UPC 

Use these members to query the universal product code(upc) for the disc. 

Returns the disc's universal product code (serial number). If the disc does not 
contain a upc, a null IString is returned. 


IString 

upc( CallType call 

Supported On: 

= wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Inherited Public Functions 


IMMRemovableMedia 

closeDoor 

isMediaPresent 

lockDoor 


IMMPlayableDevice 

addCuePoint 

position 

seekToStart 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 
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IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports Volume Adjustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. 
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IMMCDXA( unsigned long deviceldenti fier. Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMCDXA from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Implementation 

These members check if the passed in string is in the correct format to open the current device. 


isOpenStringValid 

Returns true if the passed in open string is valid for this device. 


virtual Boolean 

isOpenStringValid( const IString& deviceName) const; 


Supported On: 

PM 


Inherited Protected Functions 


IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 
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Inherited Public Data 


IMMRemovableMedia 

mediaLoadedld 




IMMDevice 

allDevices 

cuePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digital Video 

positionChangeld 

audiotape 

headphone 

sequencer 

cdxa 

microphone 

speaker 

commandN otify Id 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMFileMedia 

IMMRecordable 

IMMConfigurableAudio 


IMMDigital V ideo 
IMM W ave Audio 


—immaud.hpp 
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The IMMConfigurableAudio class is the base class for all devices that support audio. 
It provides functions for setting and querying the audio formats, speed, and audio 
channels. 


Public Functions 
Audio Attributes 

Use these members to query and set the audio attributes for the current device. 


bitsPerSample 

Returns the number of bits-per-sample. This is the number of bits of data used to 
represent each sample of each channel. The standard values are 4, 8, and 16. 
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unsigned long 

bitsPerSample( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


blockAlignment 

Returns the block alignment of data in bytes. The system processes a multiple of 
block aligned bytes of data at a time. For example, if you have a 24-byte buffer, then 
you can only set a block alignment of 2, 3, 4, 6, 8, or 12. 


unsigned long Supported On: 

blockAl ignment( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


bytesPerSecond 

Returns the average number of bytes-per-second played or recorded. This is the rate 
the data is transferred to the hardware. 

unsigned long Supported On: 

bytesPerSecond( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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.. Returns the number of audio channels set. For example, mono is 1; stereo is 2. 


unsigned long 
channels( Cal' 

Supported On: 

Hype call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Returns the interpretation of the audio format. See IMMAudioBuffer::Format (p. 

827) for more information. 

IMMAudi oBuffer:: Format Supported On: 

format ( Call Type call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


samplesPerSecond 

Returns the number of samples-per-second played or recorded. This is the sampling 
rate, in kilohertz, which each channel should use. Standard values are 11025, 22050, 
and 44100. 


unsigned long 

samplesPerSecond( CallType call = wait) const; 

Supported On: 

PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 
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Exceptions 

IlnvalidRequest The device must be in the open state before calling this function. 


setBitsPerSample 

Sets the bits-per-sample to be played or recorded. This is the number of bits of data 
used to represent each sample of each channel. The standard values are 4, 8, and 16. 
You must set an audio format using setFormat (p. 865) before calling this function. 
The file is saved in this format. 


virtual IMMConfigurableAudio& Supported On: 

setBitsPerSample( unsigned long bitsPerSample, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The value is out of range. 

IAccessError 

A audio format has not been set before calling this function. 


setBlockAlignment 

Sets the block alignment of the data. The system processes a multiple of block 
aligned bytes of data at a time. For example, if you have a 24-byte buffer, then you 
can only set a block alignment of 2, 3, 4, 6, 8, or 12. You must set an audio 
format using setFormat (p. 865) before calling this function. The file is saved in this 
format. 


virtual IMMConfigurableAudio& Supported On: 

setBlockAl ignment( unsigned long alignment, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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Exceptions 

IAccessError 

The value is out of range. 

IAccessError 

A audio format has not been set before calling this function. 


setBytesPerSecond 

Sets the average bytes per second to be played or recorded. This is the rate the data 
is transferred to the hardware. You must set an audio format using setFormat (p. 

865) before calling this function. The file is saved in this format. 


virtual IMMConfigurableAudio& Supported On: 

setBytesPerSecond( unsigned long averageBytes, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The value is out of range. 

IAccessError 

A audio format has not been set before calling this function. 


_.Sets the number of audio channels for playing and recording. Monaural is 1; stereo 
is 2. You must set an audio format using setFormat (p. 865) before calling this 
function. The file is saved in this format. 


virtual IMMConfigurableAudio& Supported On: 

setChannels( unsigned long channels, PM 

Cal Hype cal 1 = wai t); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The value is out of range. 

IAccessError 

A audio format has not been set before calling this function. 
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... Sets the audio format for playing and recording. See IMMAudioBuffer: :Format (p. 
827) for more information. The file is saved in this format. 

virtual IMMConfigurableAudio& Supported On: 

setFormat) IMMAudioBuffer::Format tag = IMMAudioBuffer::pcm, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The value is out of range. 


setSamplesPerSecond 

Sets the sampling rate for playing and recording. This is the sampling rate, in 
kilohertz, which each channel should use. Standard values are 11025, 22050, and 
44100. You must set an audio format using setFormat (p. 865) before calling this 
function. The file is saved in this format. 


virtual IMMConfigurableAudio& Supported On: 

setSamplesPerSecond) unsigned long samplesPerSecond, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The value is out of range. 

IAccessError 

A audio format has not been set before calling this function. 


Constructors 

Derived classes can use these members to create objects of this class. 
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IMMConfigurable Audio 


virtual 

'IMMConfigurableAudioO ; 


Supported On: 

PM 


Inherited Public Functions 


IMMRecordable 

canRedo 

cut 

redo 

canUndo 

deleteSelection 

save 

copy 

paste 

saveAs 

cueForRecording 

record 

undo 


IMMFileMedia 

filename 

isReadOnly 

load 


IMMPlayableDevice 

addCuePoint 

position 

seekToStart 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 
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IMMDevice 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports V olume Adj ustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

Derived classes can use these members to create objects of this class. 


IMMConfigurableAudio 

Q IMMConfigurableAudio( const IString& deviceName, Supported On: 

Boolean openNow = true, PM 

unsigned long instance = 0, 

Boolean openShareable = true); 

A derived class can construct an IMMConfigurableAudio from the following: 
deviceName 

You must specify what device you wish to construct. 
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openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 

instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 

Q IMMConfigurableAudio( unsigned long deviceldentifier. Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMConfigurableAudio from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Implementation 

These members translate the audio command to device-specific values. 

translateAudioFlag 

Allows subclasses to map the general audio commands to the device-specific values. 
For example, the digital video and the wave audio device both support setting the 
bytes-per-second, but the actual system values are different. By allowing the 
mapping of the wave audio values to the digital video values, the digital video player 
does not have to override all of the audio functions because they call this function. 

virtual unsigned long Supported On: 

translateAudioFlag( unsigned long) const; PM 


Inherited Protected Functions 


IMMFileMedia 

setReadOnlyFlag 




IMMDevice 

deviceWindow 

open 

setOpenStatus 
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IMMDevice 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Inherited Public Data 


IMMDevice 

allDevices 

cuePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digital Video 

positionChangeld 

audioTape 

headphone 

sequencer 

cdxa 

microphone 

speaker 

commandN otify Id 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


I Base 

recoverable 

unrecoverable 
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IMMCuePointEvent 


IBase 

IVBase 

IEvent 

IMMCuePointEvent 


_.None. 

-Jmmevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

870 

userParameter 

871 

device 

871 

'IMMCuePointEvent 

870 

position 

871 




The IMMCuePointEvent class is the class for cue point events. A cue point event 
gets generated whenever a device passes over one of its set cue points. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMCuePointEvent 

Although you can construct objects of this class, typically 

IMMDeviceHandler::dispatchHandlerEvent (p. 910) creates objects of this class from 
an object of the class IEvent (Vol. II) or another IMMCuePointEvent object. 

IMMCuePointEvent( const IEvent& event); Supported On: 

PM 


"IMMCuePointEvent 

virtual 

'IMMCuePointEvent(); 


Supported On: 

PM 
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Event Information 

Use these members to return the position, device and user parameter for the device that generated 
this event. 

Returns a pointer to the device that played or recorded over a cue point. 

IMMDevi ce* Supported On: 

device() const; PM 

..Returns the cue point position. 

I MMT i me Supported On: 

position() const; PM 


userParameter 

Returns the user parameter that was set at the time of this event. See 
IMMDevice::setUserParameter (p. 895) for more information. 

Supported On: 

PM 


unsigned short 
userParameter() const; 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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I MM Dev ice 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 


IMMAmpMixer 

IMMPlayableDevice 


_immdev.hpp 


Member 

Page 

Member 

Page 

Constructor 

892 

isConnectorEnabled 

883 

acquire 

889 

isOpen 

886 

aliasName 

884 

isOpenStringValid 

894 

allDevices 

898 

itemCapability 

894 

ampMixer 

898 

itemStatus 

894 

animation 

898 

lastError 

893 

audioCD 

898 

microphone 

899 

audioTape 

898 

mode 

885 

cdxa 

898 

monitor 

899 

close 

886 

open 

887 

commandNotifyld 

900 

openOnThread 

887 

connectedDeviceld 

882 

openStatus 

897 

cuePointld 

900 

other 

899 

dat 

898 

overlay 

899 

deletePendingEvents 

885 

passDeviceld 

900 

description 

885 

positionChangeld 

901 

deviceEventld 

900 

prerollTime 

888 

deviceld 

884 

prerollType 

888 

deviceName 

884 

release 

890 

deviceType 

885 

requiresFiles 

876 

deviceWindow 

893 

sendCommand 

894 

digital Video 

898 

sequencer 

899 

disableAudio 

874 

setCloseOnDestroy 

888 

disableConnector 

882 

setLastError 

893 

enableAudio 

875 

setOpenStatus 

897 

enableConnector 

882 

setPassDeviceRequested 

895 

headphone 

899 

setSpeedFormat 

890 

isAcquired 

889 

setTimeFormat 

891 

isAudioEnabled 

875 

setU serParameter 

895 

isCloseOnDestroy 

886 

setVolume 

875 

isConnectionSupported 

883 

speaker 

899 
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Member 

Page 

speedFormat 

891 

supportsAudio 

877 

supportsCommand 

877 

supportsDigitalTransfer 

877 

supportsDisableEject 

878 

supportsEject 

878 

supportsPlay 

878 

supportsRecord 

879 

supportsRecordlnsertion 

879 

supportsSave 

880 

supportsStreaming 

880 


Member 

Page 

supports Video 

880 

supports Volume Adjustment 

881 

timeFormat 

891 

userParameter 

896 

videoDisc 

899 

videoTape 

899 

volume 

876 

wasPassDeviceRequested 

896 

waveAudio 

900 

'IMMDevice 

884 


The IMMDevice class is the base device class and provides behavior common to all 
devices. IMMDevice contains the device ID, alias, and similar information. There 
are numerous functions for querying the capabilities of the device. Also, there are 
functions for opening and closing the device, changing the speed and time formats, 
and for changing the audio. 


Public Functions 


Audio 

Use these members to manipulate the audio for the device. You can turn the audio off and on, 
and you can change and query the volume. 

—Turns off the audio for the device. This audio change can be delayed based on the 
passed in vectored delay time (think of this the same as fade out on your car stereo). 
Based on this delay time, the audio is slowly turned off. The default is no delay. 


virtual IMMDevice& Supported On: 

di sabl eAudio( PM 

AudioChannel channel = all, 

const IMMMillisecondTime& over = IMMMi11isecondTime ( ), 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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_Turns on or turns off the audio for the device. This audio change can be delayed 
based on the passed in vectored delay (think of this the same as fade in on your car 
stereo). Based on this delay time, the audio is slowly turned on. The default is no 
delay. 


virtual IMMDevice& Supported On: 

enableAudio( PM 

Boolean enable = true, 

AudioChannel channel = all, 

const IMMMi 11isecondTime& over = IMMMi11isecondTime ( ), 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


isAudioEnabled 

Returns true if the audio for the passed in channel is turned on. 


Boolean 

isAudioEnabled( AudioChannel channel = al1, 
Cal Hype cal 1 = wai t); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


-Sets the volume of the audio channel for the device to a percent (from 0% to 100%) 
of the maximum audio level. This volume change can be delayed based on the passed 
in vectored delay time (think of this the same as fade in or fade out on your car 
stereo). Based on this delay time, the volume is slowly changed to the new volume. 
The default is no delay. 
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virtual IMMDevice& Supported On: 

setVolume( unsigned long volume, PM 

AudioChannel channel = all, 

const IMMMi11isecondTime& over = IMMMi11isecondTime ( ), 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Returns the volume setting for the passed in audio channel. This value is in the 
range of 0 to 100. 


virtual unsigned long 
volume( AudioChannel channel = left, 
CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Capabilities 

Use these members to determine the capabilities of the device. All devices should respond to 
these inquiries. 

_ Returns true if the device requires the use of files. An example of a device that 
requires files is the wave audio device, and an example of a device that does not 
require files is the amplifier-mixer device. 


Boolean 

requiresFi1es( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 
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supportsAudio 


Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

Returns true if the device has support for audio playback. 

Boolean 

supportsAudio( 

Supported On: 

Call Type call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsCommand 

Returns true if the device supports the passed in command. 


Boolean 

supportsCommand( IMMNotifyEvent::Command command, 
Call Type call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsDigitalTransfer 

Returns true if the device can internally process digital data, for example a 
digital-to-analog converter on a CD player. 

Boolean Supported On: 

supportsDigi tal Transfer( Call Type call = wait) const; PM 
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Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsDisableEject 

Returns true if the device can disable the manual ejection of the media. 

Bool ean Supported On: 

supportsDisableEject( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsEject 

Returns true if the device can eject the media. 


Boolean 

supportsEject( Cal 

Supported On: 

Hype call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


_ Returns true if the device can play. 

Boolean Supported On: 

supportsPlay( CallType call = wait) const; PM 


878 Open Class Library Reference 






IMMDevice 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsRecord 

Returns true if the device supports recording. This does not necessarily mean it also 
supports the ability to save the data you just recorded. See supportsSave (p. 880) for 
more information. 


Boolean Supported On: 

supportsRecord( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsRecordlnsertion 

Returns true if the device supports insertion of data while recording. For example, 
you would use this function if you just recorded a sound file and then wanted to 
record your voice saying "Hello" in the middle of it without overlaying any of the 
recorded sound. 


Boolean Supported On: 

supportsRecordlnsertionj CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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supportsSave 

Returns true if the device can save data to some type of media (for example a file). 
An example of a device that supports saving is the wave audio device, and an 
example of a device that does not support saving is the audio CD device. 


Bool ean Supported On: 

supportsSave( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsStreaming 

Returns true if the device can continuously transfer digital data to or from another 
device. The source or destination of the data is determined by the device's 
connections. 

Bool ean Supported On: 

supportsStreaming( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsVideo 

Returns true if the device has support for video playback. 


Boolean 

supportsVideo( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsVolumeAdjustment 

Returns true if the device supports software control of the volume. An example of a 
device that supports volume adjustment is the wave audio device, and an example of 
a device that does not support audio adjustment is the video disc device. 


Boolean Supported On: 

supportsVolumeAdjustment( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Connector Type 

Use these members to query and manipulate the connectors for the device. 

Connectors give devices the ability to connect to other devices. For those of you who have 
VCRs or stereos, you probably are familiar with those RCA connection cables that you use to 
connect different stereo and video components. You normally connect one end of the cable to a 
line in (such as video in on your TV) and connect the other end to the line out (such as video 
out on your VCR). Think of these software connections and connectors as those cables and 
connections. 

For example, suppose you want to record your favorite song from a cassette as a sound file on 
your computer, but you do not have a microphone. You do, however, have a RCA cable 
connected to your stereo. You could connect one end of the cable to your cassette player and the 
other to the line in of your sound card. By default, the wave audio device would record from the 
microphone jack on the sound card because it is initially connected to the microphone connector. 
To record from the sound card's line in, you would have to make your wave audio device record 
from the line in connector on the sound card. To do this, you would enable the line in connector 
for your audio device by calling enahleComiectoii IM M Device:: line hi )\ on your audio device. 
Because the audio device only supports one input connection to be enabled at a given time, it 
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automatically disables the microphone connector. So, to create the sound file all you would have 
to do is to press play on the cassette player and call the record function on the wave audio 
device. 


connectedDeviceld 

Returns the Id of the device that is connected to the identified connector of this 
device. 


unsigned long Supported On: 

connectedDeviceId( ConnectorType type, PM 

CallType call = wait) const; 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


disableConnector 

Turns off the connector specified by type for this device. 


virtual IMMDevice& 

disableConnector( ConnectorType type. 

Cal 1 Type cal 1 = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

The connector type is not supported by this device. 


enableConnector 

Turns on or turns off the connector specified by type for this device. 
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virtual IMMDevice& Supported On: 

enableConnector( ConnectorType type, PM 

Boolean enable = true. 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

The connector type is not supported by this device. 


isConnectionSupported 

Returns true if the connector is valid for this device. 


Boolean Supported On: 

isConnectionSupported( ConnectorType type, PM 

CallType call = wait) const; 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


isConnectorEnabled 

Returns true if the connector is enabled for this device. 


Boolean Supported On: 

isConnectorEnabled( ConnectorType type, PM 

CallType call = wait) const; 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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Constructors 

Derived classes can use these members to create objects of this class. 

"IMMDevice 


virtual 
'IMMDeviceO ; 


Supported On: 

PM 


Device Information 

Use these members to query information about the device and its state. 

-.Returns the alias associated with the device during the open procedure. This 
function is can return an empty string because a device can be constructed solely 
from a device ID. 


IString Supported On: 

aliasName() const; PM 

..Returns the ID of the current device. This value is used by the system to identify 
the device. In the construction of this object, a device identifier is passed in. 


unsigned long Supported On: 

deviceld() const; PM 


Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

...Returns the name 

of the device depending on the class of the object. For example. 


some devices can be opened with a file name (song.mid), but others devices such as, 
IMMAudioCD, is opened with a specific device name (such as CDAUDIOOl). 


IString 

deviceName() const; 


Supported On: 

PM 


Device Type and Description 

Use these members to query the type and description of the device. 
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-Returns the description of the hardware associated with this device. 

IString Supported On: 

description( CallType call = wait) const; PM 

—Returns the type of the device. 


unsigned long Supported On: 

deviceType( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Event Type and DeletePendingEvents 

Use these members to specify the type of pending events that are to be deleted. 


deletePendingEvents 

Removes all of the passed in event types from the queue. 


virtual IMMDevice& 

deletePendingEvents( EventType event = all Events); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Mode 

Use these members to query the current mode of the device. 
Returns the current mode of the device. 
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virtual Mode 
mode( CallType cal 

Supported On: 

1 = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Opening and Closing 

Use these members to query if the device is opened, to open or close the device, and to direct 
the device to close itself when the device object is destructed. 

Closes a device. 


virtual IMMDevice& 
close( CallType call = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


isCloseOnDestroy 

Returns true if the device closes itself when the device object is deleted. 


Boolean Supported On: 

isCloseOnDestroy() const; PM 

Returns true if the device is opened. In general, open a device before calling 
multimedia functions. 

Boolean Supported On: 

isOpen() const; PM 


Exceptions 

IAccessError The device identifier is not valid. 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; 

possibly another 


device of this same type was acquired for exclusive use in 

this or another 


process. 


IAccessError 

An internal driver error occurred. 



.Opens the device or file based on the passed in string. The default string uses the 
deviceName. Note, if call is wait (p. 901), then the windowing system will be tied 
up until the file or device is opened. If you do not want to tie up the windowing 
system and you do not want the open function to return until the file or device is 
opened, then use the openOnThread (Vol. II) function. Otherwise, you could set call 
to nowait (p. 901), causing open to return immediately. When the open finishes an 
INotificationEvent (Vol. I), is sent to any observers that are attached to this device, 
notifying them that the open is finished. 

You must have opened the device before you try to acquire (p. 889) access to it. 

When a device is open, it notifies the operating system that you want to have the use 
of the hardware at sometime in the future, and notifies the operating system that it 
can share the device. When you acquire access, you are requesting that the system 
provide you access to the hardware now. Then, based on the type of ShareMode (p. 
903) that you requested, it gives you access to the hardware. 

virtual IMMDevice& Supported On: 

open( const IString& fileOrDevice = IString ( ), PM 

Boolean shareable = true. 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; 

IAccessError 

An internal driver error occurred. 

IAccessError 

The device is locked. 

IAccessError 

A hardware error occurred. 


openOnThread 

Opens the file or device by creating a thread to do the actual opening. The default 
string uses the deviceName. By doing the opening this way, it does not tie up the 
windowing system. This function does not return until the file or device is opened. 


virtual IMMDevice& Supported On: 

openOnThread( const IString& fileOrDevice = IString ( ), PM 

Boolean shareable = true. 

Cal 1 Type cal 1 = wait); 
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Exceptions 

IAccessError 

The device identifier is not valid; 

IAccessError 

An internal driver error occurred. 

IAccessError 

The device is locked. 

IAccessError 

A hardware error occurred. 


setCloseOnDestroy 

Closes the device when this object is destroyed. The default is to close the device. 

IMMDevi ce& Supported On: 

setCloseOnDestroy( Boolean close = false); PM 


Preroll Type 

Use these members to prepare a device to begin a playback or recording function with minimal 
delay. These members set and query the amount of preroll time. 

—Returns the amount of preroll time in IMMTime (p. 1026). If the returned time 
object is invalid then the preroll time is not bounded. 


IMMTime Supported On: 

prerollTime( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


—Returns the preroll characteristics of the device. 


Prerol Hype 

prerollType( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 


888 Open Class Library Reference 






IMMDevice 


Exceptions 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Share Mode and Acquiring 

Use these members to specify the three ways that the operating system can share access to the 
device and to query, acquire, and release access to the device. 

.Requests assignment of (access to) the device. If queued is true, the request is 
queued and executed as soon as the device resources are available. If the request can 
be satisfied immediately, then it is not queued. 

You must have opened the device before you try to acquire access to it. When a 
device is open, it notifies the operating system that you want to have the use of the 
hardware at sometime in the future, and notifies the operating system that it can share 
the device. When you acquire access, you are requesting that the system provide you 
access to the hardware now. Then, based on the type of ShareMode (p. 903) that you 
requested, it gives you access to the hardware. 

virtual IMMDevice& 

acquire( ShareMode acquire = shareable. 

Boolean queuedForResources = false, 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Supported On: 

PM 


-Returns true if the device is ready. If a device is not ready, then access to it needs 
to be acquired using acquire (p. 889). 

Boolean 

isAcquired( CallType call = wait) const; 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

Releases exclusive use of the device resources. 

virtual IMMDevice& 
release( CallType 

Supported On: 

cal 1 = wai t); PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Speed and Time 

Use these members to set and query the current formats for speed and time for the device. 


setSpeedFormat 

Sets the speed format for the device. See IMMSpeed (p. 1024) for more information 
on the different speed formats. 


virtual IMMDevice& 

setSpeedFormat( IMMSpeed::Format format. 
Cal 1 Type cal 1 = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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setTimeFormat 

Sets the time format for the device. See IMMTime::Format (p. 1032) enumeration for 
more information on the different time formats. 


virtual IMMDevice& Supported On: 

setTimeFormat( IMMTime::Format format, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

— Returns the currently set speed format for the device. See IMMSpeed (p. 1024) for 
more information on the different speed formats. 

IMMSpeed::Format 
speedFormat( Call 

Supported On: 

Type call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


—Returns the currently set time format for the device. See the Format (p. 1032) 
enumeration for more information on the different time formats. 


IMMTime::Format 

timeFormat( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 
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Exceptions 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Inherited Public Functions 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

Derived classes can use these members to create objects of this class. 

IMMDevice 

[J IMMDevice( const IStringS fi 1 eOrDevice); Supported On: 

PM 


A derived class can construct an IMMDevice from: 
fileOrDevice 

This is the name of the device. This name is operating system specific. 
For example the name of the amplifier/mixer device in OS/2 is 
AMPMIX. 
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@ IMMDevice( unsigned long deviceldentifier, Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMDevice from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Error Information 

Use these members to set and query an error value. 

Returns the return code from the last call. This return code could be 0 because the 
value is reset with each call. If an error code needs to be captured, this function 
should be called directly after the error-causing function because each function 
overwrites this value. 

unsigned long Supported On: 

lastError() const; PM 

IPM Because the system multimedia architecture does not keep track of the return value 
of the last function call, this function does that. It allows all of the functions to 
throw exceptions where they are meaningful. 

_.Sets the return code of the last low-level function call. 

IMMDevice& Supported On: 

setLastError( unsigned long errorld); PM 

IPM Because the system multimedia architecture does not keep track of the return value 
of the last function call, this function does that. It allows all of the functions to 
throw exceptions where they are meaningful. 

Implementation 

Use these members to access the low-level functions and to set and query a user parameter that 
can be passed on function calls. 


deviceWindow 

Returns the window object that the device uses to communicate to the operating 
system. 

IWindow& Supported On: 

deviceWindow() const; PM 
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isOpenStringValid 

Returns true if the passed in open string is valid for this device. 

virtual Boolean Supported On: 

isOpenStringVal id( const IString& deviceName) const; PM 


itemCapability 

Gets the device capabilities for the item. This is similar to using the devQueryCaps 
system call on the OS/2 operating system. 


unsigned long Supported On: 

itemCapabi 1 ity( unsigned long item, PM 

Cal 1 Type cal 1) const; 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


_ Checks the status of the item. 


unsigned long 
itemStatus( unsigned long 
unsigned long 
Call Type call 


i tern, 
value = 
= wait) 


0 , 

const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


sendCommand 

Sends a command string to the device. This returns the resulting string from the call. 


894 Open Class Library Reference 





IMMDevice 


El 


IString 

sendCommand( const IString& 
unsigned short 


command, 
userParm); 


Supported On: 

PM 


The passed in userParameter is in the notification message and does not replace the 
value set with setUserParameter (p. 895). 


g IString 

sendCommand( const IString& command); 


Supported On: 

PM 


The currently set userParameter (p. 896) is in the notification message. 


^ IMMDevice& Supported On: 

sendCommand( unsigned short message, PM 

unsigned long paraml, 
void* param2); 

The currently set userParameter (p. 896) is in the notification message. 


[] IMMDevice& Supported On: 

sendCommand( unsigned short message, PM 

unsigned long paraml, 
void* param2, 
unsigned short userParm); 

The passed in userParameter is in the notification message and does not replace the 
value set with the setUserParameter (p. 895). 

setPassDeviceRequested 

Sets the pass device flag. Use this to notify the device object that the device object 
has received use of the actual hardware device. Until the device receives the first 
pass device event, the device is not initialized. 


IMMDevice& 

setPassDeviceRequested( Boolean sawPassDevice); 


Supported On: 

PM 


setUserParameter 

Sets the user parameter. This parameter is automatically passed in the notification 
messages for all but two of the device functions. The exceptions are the two 
sendCommand (p. 894) functions that take their own user parameter. 

IMMDevice& Supported On: 

setllserParameter( unsigned short userParm = 0); PM 
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userParameter 

Returns the user parameter that is in the all of the notification messages except for 
the two sendCommand (p. 894) functions that take their own user parameter. 

unsigned short Supported On: 

userParameter() const; PM 

wasPassDeviceRequested 

Returns true if it has already processed a passDevice event. Use this to notify the 
device object that the device object has received use of the actual hardware device. 
Until the device receives the first pass device event, the device is not initialized. 

Bool ean Supported On: 

wasPassDeviceRequested() const; PM 


Opening and Closing 

Use these members to query if the device is opened, to open or close the device, and to direct 
the device to close itself when the device object is destructed. 

Opens the device. 

Note: Do not use open for devices that take a while to open because it ties up the 
windowing system till the device is opened. Use the openOnThread function 
for this case. 


virtual IMMDevice& Supported On: 

open( unsigned long instanceNumber, PM 

Boolean shareable = true. 

Call Type call = nowait); 


Exceptions 

IAccessError 

The device identifier is not valid; 

IAccessError 

An internal driver error occurred. 

IAccessError 

The device is locked. 

IAccessError 

A hardware error occurred. 


_Opens the device by creating a thread to do the actual opening. By doing the 
opening this way, it will not tie up the windowing system. 


virtual IMMDevice& 

openOnThread( unsigned long instanceNumber, 
Boolean shareable = true); 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device identifier is not valid; 

IAccessError 

An internal driver error occurred. 

IAccessError 

The device is locked. 

IAccessError 

A hardware error occurred. 


OpenStatus 

Use these members to set and query the open state of the device. 

_ Returns the result of the open attempt. This is used by the device to determine if 
the opening of the device has occurred yet and if it was successful. This is important 
because basically all of the multimedia function calls require the device to be opened 
first before you can make any calls. 

OpenStatus Supported On: 

openStatus() const; PM 


setOpenStatus 

Sets the open flag. This is used by the device to determine if the opening of the 
device has occurred yet and if it was successful. This is important because basically 
all of the multimedia function calls require the device to be opened first before you 
can make any calls. 


IMMDevice& 
setOpenStatus ( 

OpenStatus status); 

Supported On: 

PM 

Inherited Protected Functions 

IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Public Data 
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Device Type and Description 

Use these members to query the type and description of the device. 

_A device type for representing all devices. 

static const unsigned long Supported On: 

allDevices; PM 

_A device type for representing a combination amplifier-mixer that is used to control 
the characteristics of an audio signal from one or more audio sources. 

static const unsigned long Supported On: 

ampMixer; PM 

_A device type for representing a device that uses a sequence of images to produce 
the effect of movement. 


static const unsigned long Supported On: 

animation; PM 

A device type for representing an audio CD device. 


static const unsigned long Supported On: 

audioCD; PM 

_A device type for representing an audio tape recorder device. 


static const unsigned long Supported On: 

audioTape; PM 

A device type for representing a compact disc-extended architecture CD-XA device. 


static const unsigned long Supported On: 

cdxa; PM 

A device type for representing a digital audio tape device. 


static const unsigned long Supported On: 

dat; PM 

_A device type for representing a digital video device. 


static const unsigned long 
digitalVideo; 


Supported On: 

PM 
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_A device type for representing a headphone. 

static const unsigned long Supported On: 

headphone; PM 

_A device type for representing a microphone. 


static const unsigned long Supported On: 

microphone; PM 

A device type for representing a device that can listen to (monitor) an audio and 
video source. 


static const unsigned long Supported On: 

monitor; PM 

A device type for representing devices other than the system-provided device types. 


static const unsigned long Supported On: 

other; PM 

A device type for representing a device that can overlay an image on top of the 
screen that does not disrupt what is displayed there. 


static const unsigned long Supported On: 

overlay; PM 

_A device type for representing a MIDI synthesizer device. 


static const unsigned long Supported On: 

sequencer; PM 

_A device type for representing output to the speakers. 


static const unsigned long Supported On: 

speaker; PM 

_A device type for representing a video disc player device. 


static const unsigned long Supported On: 

videoDisc; PM 

_A device type for representing a video tape device. 
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static const unsigned long Supported On: 

videoTape; PM 

_A device type for representing a device that uses digital audio data in the wave 
format. 


static const unsigned long 
waveAudio; 


Supported On: 

PM 


Notification Event Descriptions 

These INotificationld strings are used for all notifications that IMMDevice provides to its 
observers. 


commandNotifyld 

Provides a notification identifier to observers when one of the IMMDevice functions 
has been called with the notify flag. IMMDevice provides a pointer to an 
IMMNotifyEvent (p. 965) for the command in the INotificationEvent::eventData (Vol. 
I) field of the INotificationEvent (Vol. I). 

static const INotificationld Supported On: 

commandNotifyld; PM 

-.Provides a notification identifier to observers when the device receives a cue point 
message. IMMDevice provides a pointer to an IMMCuePointEvent (p. 870) for the 
message in the INotificationEvent::eventData (Vol. I) field of the INotificationEvent 
(Vol. I). 

static const INotificationld Supported On: 

cuePointld; PM 


deviceEventld 

Provides a notification identifier to observers when the device receives a device 
message. IMMDevice provides a pointer to an IMMDeviceEvent (p. 905) for the 
message in the INotificationEvent::eventData (Vol. I) field of the INotificationEvent 
(Vol. I). 

static const INotificationld Supported On: 

deviceEventld; PM 

-.Provides a notification identifier to observers when the device receives a pass 
device message. IMMDevice provides a pointer to an IMMPassDeviceEvent (p. 969) 
for the message in the INotificationEvent::eventData (Vol. I) field of the 
INotificationEvent (Vol. I). 
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static const INotificationld Supported On: 

passDeviceld; PM 

positionChangeld 

Provides a notification identifier to observers when the device receives a position 
change message. IMMDevice provides a pointer to an IMMPositionChangeEvent (p. 
995) for the message in the INotificationEvent::eventData (Vol. I) field of the 
INotificationEvent (Vol. I). 


static const INotificationld 
positionChangeld; 


Supported On: 

PM 


Inherited Public Data 


IStandardNotifier 

deleteld 




Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Call Type { 

nowait = 0X00000001, 
wait = 0x00000002 
}; 


This enumeration determines how the multimedia functions call the low level 
operating system functions. In both call types, a notification event is sent to all 
attached IObservers (Vol. I) when the command finishes processing. Most functions 
that result in a call to the operating system take this type as their last parameter. The 
following are valid values: 

nowait 

The method is asynchronous and returns immediately (before the requested 
processing is complete). If you want to know when the command finishes 
processing, attach an observer to the device because it gets notified when the 
command finishes. 
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wait 

The method is synchronous and all processing occurs before the function 
returns. Wait is not recommended for threads having a message queue that is 
processing messages for user interface windows. A long wait could tie up the 
message queue. 


OpenStatus { 

openNotAttempted, 
openSuccessful, 
openFai1ed 
}; 


An enumeration that denotes the different states for opening a device. The following 
are valid values: 

openNotAttempted 

You have not tried to open the device yet. 

openSuccessful 

The open succeeded. 

openFailed 

The open failed. 


Preroll Type { 
variable = 1, 
fixed, 
none 
}; 


Use these enumerators to specify preroll characteristic identifiers. Preroll means 
preparing a device to begin a playback or recording function with minimal delay. 
The following are valid values: 

variable 

The preroll time for the device is variable, meaning that you can change the 
preroll time value. 

fixed 

The preroll time for the device is fixed, meaning that you cannot change the 
preroll time value; it is fixed by the operating system. 

none 

The preroll time is not supported by the device. 


AudioChannel 
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AudioChannel { 
all, 
left, 
ri ght 
}; 


Use this enumeration to specify audio channel identifiers. 


Mode { 

notReady = 1, paused, playing, stopped, recording, 

seeking 

}; 


An enumeration that denotes the current state of the device. The following are valid 
values: 

notReady 

A device is in this state when the device is not acquired. 

paused 

The device is paused. 

playing 

The device is playing. 

stopped 

The device is stopped. 

recording 

The device is recording. 

seeking 

The device is moving the current position to a new location. 

EventType { 

allEvents, notifyEvent = 0x0500, passDeviceEvent, 

positionChangeEvent, cuePointEvent, deviceEvent, 

synchEvent 

}; 


Use the preceding enumerations to specify the type of events that are to be removed. 


ShareMode { 
shareable, 

isolatedExclusive = 0x00000100, 
exclusive = 0x00000200 
}; 


Use these enumerators to specify share mode identifiers: 
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shareable 

Allows the device to be shared by other applications. 

isolatedExclusive 

Inhibits other applications from acquiring use of the physical (or hardware) 
device until released by the owning application. 

exclusive 

Acquires the device for exclusive use without acquiring the entire device 
resource for exclusive use. This basically means that the operating system 
cannot make this device inactive. 


ConnectorType 

ConnectorType { 

midi Stream = 0x00000001, 
waveStream = 0x00000003, 
xaStream = 0x00000005, 
speakers = 0x00000007, 
lineln = 0x00000009, 
videoin = 0x0000000b, 
phoneSet = OxOOOOOOOd, 
audioin = 0xO00OOOOf, 
universal = 0x00000011 
}; 


cdStream = 0x00000002, 
ampStream = 0x00000004, 
headphones = 0x00000006, 
microphones = 0x00000008, 
lineOut = 0x0000000a, 
videoOut = 0xOO0OOO0c, 
phoneLine = OxO0OOO00e, 
audioOut = 0x00000010, 


Use the preceding enumerations to specify connection types. These are all of the 
types of connections that a device can support. Each device only supports a 
subsection of this list. For example, an audio CD device would not support xaStream 
or microphones. 

Note: Stream in these enumerations means the digital transfer of the data for these 
devices. 
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IBase 

IVBase 

IEvent 

IMMDeviceEvent 


_.None. 


_ immevt.hpp 
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The IMMDeviceEvent class is the class for device events. These events get generated 
by devices for device-specific purposes. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMDeviceEvent 

Although you can construct objects of this class, typically 

IMMDeviceHandler::dispatchHandlerEvent (p. 910) creates objects of this class from 
an object of the class IEvent (Vol. II) or another IMMDeviceEvent object. 

IMMDeviceEvent( const IEvent& event); Supported On: 

PM 


IMMDeviceEvent 

virtual 

"IMMDeviceEvent(); 


Supported On: 

PM 
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Event Information 

Use these members to return the device, event code, and event data for the device that generated 
this event. 

Returns a pointer to the device that this event is from. 

IMMDevice* 
device() const; 

_ Returns the device-specific event code. 

unsigned short 
eventCode() const; 

-Returns the device-specific event data structure. 

void* Supported On: 

eventData() const; PM 


Supported On: 

PM 


Supported On: 

PM 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

IHandler 

IMMDeviceHandler 


IMMRemovableMediaHandler 
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The IMMDeviceHandler class is the base handler class for IMMDevices and provides 
behavior common to all devices. IMMDeviceHandler inherits from IHandler. It 
inherits dispatchHandlerEvent virtual function from IHandler to encapsulate the 
multimedia interface. This function does four things. First, it determines what 
message has been received and converts it into the appropriate event. Second, it 
determines which device the event is for. Third, it calls the virtual function for the 
event. Fourth, it goes through the list of added IObservers for the device and calls 
the IObserver::dispatchNotificationEvent with the event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMDeviceHandler 


IMMDeviceHandler(); 


Supported On: 

PM 
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"IMMDeviceHandler 


virtual 

'IMMDeviceHandler(); 


Supported On: 

PM 


Device Attachment 

Use these members to attach and detach the handler object to and from a given device. 


handleEventsFor 

Attaches the handler to the specified IMMDevice (p. 873) object. 

Supported On: 

PM 

stopHandlingEventsFor 

Detaches the handler from the specified IMMDevice (p. 873) object. 


virtual IMMDeviceHandler& 
handleEventsFor( IMMDevice* device); 


virtual IMMDeviceHandler& 

stopHandlingEventsFor( IMMDevice* device); 


Supported On: 

PM 


Event Processing 

Derived classes must supply these members to process a device, position change, pass, or cue 
point event. 

-Implemented by derived classes to process cuePoint events. 

virtual Boolean Supported On: 

cuePoint( const IMMCuePointEvent& event); PM 

-.Implemented by derived classes to process device events. 


virtual Boolean Supported On: 

deviceEvent( const IMMDeviceEvent& event); PM 

..Implemented by derived classes to process pass device events. 


virtual Boolean 

passDevice( const IMMPassDeviceEvent& event); 


Supported On: 

PM 
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positionChange 

Implemented by derived classes to process position change events. 


virtual Boolean 

positionChange( const IMMPositionChangeEvent& event); 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process. If it is, these members call the virtual function used to process the event. 

dispatchHandlerEvent 

This function does four things. First, it determines what message has been received 
and converts it into the appropriate event. Second, it determines which device the 
event is for. Third, it calls the virtual function for the event. Fourth, it goes through 
the list of added IObservers for the device and calls the 
IObserver::dispatchNotificationEvent with the event. 

A given handler should return true if the event should not be dispatched to other 
handlers. In such cases, a result can be placed in the specified IEvent (Vol. II) 
object. 
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virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM 


Inherited Protected Functions 



Inherited Protected Data 
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IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMFileMedia 

IMMRecordable 

IMMConfigurableAudio 

IMMDigitalVideo 


_.None. 


_Jmmdigvd.hpp 
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The IMMDigitalVideo class provides behavior for digital software motion video. It 
supports playback of video in either a system-provided default window or a 
user-specified window. It provides functions for playing and controlling video in a 
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default window or an application window. There are also functions for playing the 
video at different speeds. 


Public Functions 
Capabilities 

Use these members to query the capabilities for the current device. 


supportsOverlayGraphics 

Returns true if the device supports the display by an application of overlay graphics 
in a video window. 

Boolean Supported On: 

supportsOverl ayGraphi cs ( Call Type call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsReverse 

Returns true if the device can play in reverse. 


Boolean 

supportsReverse( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsSizing 

Returns true if the device can independently stretch the horizontal and vertical 
dimensions of the image. This is different than supportsStretchToFit (p. 914), which 
forces both horizontal and vertical dimensions to be stretched in the same proportion. 
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For example, if you stretch the horizontal dimension by 10%, then the vertical 
dimension must stretch by 10%. 

Boolean Supported On: 

supportsSizing( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


supportsStretchToFit 

Returns true if the device can stretch the video frames to fill the display rectangle. 
Thus, both the horizontal and vertical dimensions must be stretched by the same 
proportion. For example, if you stretch the horizontal dimension by 10%, then the 
vertical dimension must stretch by 10%. This is different than supportsSizing (p. 
913), which allows both horizontal and vertical dimensions to be stretched 
independently of each other. 


Bool ean Supported On: 

supportsStretchToFit( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Constructors 

You can construct and destruct objects of this class. 


IMMDigitalVideo 

IMMDigital Video( Boolean openNow = true. Supported On: 

unsigned long instance = 0, PM 

Boolean openShareable = true); 
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You can construct an IMMDigitalVideo front the following: 

openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 

instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 


"IMMDigitalVideo 


virtual 

'IMMDigitalVideoO ; 


Supported On: 

PM 


Playback 

Use these members to play a video at different rates. 

isPlayingForward 

Returns true if the play direction is forward or if the device is not playing. 

Boolean Supported On: 

isPlayingForward( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Plays the video at the specified speed from the start position to the end position. If 
from is omitted, play starts at the current position; if to is omitted, play stops at the 
end of the video file. 
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IMMDi gi tal Vi deo& Supported On: 

p!ayAt( const IMMSpeed& speed, PM 

const IMMTime& from = IMMTime ( ), 
const IMMTime& to = IMMTime ( ), 

Call Type call = nowait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the video file. 


.Plays the video at the fast speed from the start position to the end position with no 

audio. If from is omitted, play starts at the current position; if to is omitted, play 
stops at the end of the video file.. 

IMMDigitalVideo& 

playFast( const IMMTime& from = IMMTime ( ), 
const IMMTime& to = IMMTime ( ), 

CallType call = nowait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the video file. 


Supported On: 

PM 


_Plays frames when indexed; otherwise, it plays the video as fast as possiblefwithout 
disabling the video) from the start position to the end position with no audio. If from 
is omitted, play starts at the current position; if to is omitted, play stops at the end of 
the video file. 
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IMMDigitalVideo& 

Supported On: 

playScan( const IMMTime& from = IMMTime ( ), 

PM 

const IMMTime& to = IMMTime ( ), 


Call Type call = nowait); 



Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the video file. 


...Plays the video at the slow speed from the start position to the end position with no 
audio. If from is omitted, play starts at the current position; if to is omitted, play 
stops at the end of the video file. 

IMMDi gi tal Vi deo& Supported On: 

playSlow( const IMMTime& from = IMMTime ( ), PM 

const IMMTime& to = IMMTime ( ), 

Call Type call = nowait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the video file. 


Playback Speeds 

Use these members to query the device's playback rates and the current playback rate. 
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.Returns the device's fast playback rate in the current speed format, either as a 

percentage or in frames-per-second. Returns 0 if the device cannot play fast. 


IMMSpeed Supported On: 

fastSpeed( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


fileNormalSpeed 

Returns the normal play rate of the currently loaded video file, in the current speed 
format, either as a percentage or in frames-per-second. This is the playback speed 
stored in the video file when the video file was created. Returns 0 if no file is 
currently loaded. 


IMMSpeed Supported On: 

fi 1 eNormalSpeed( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


maximumSpeed 

Returns the maximum play rate in the current speed format, either as percentage or in 
frames-per-second. 

IMMSpeed 

maximumSpeed( CallType call = wait) const; 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


minimumSpeed 

Returns the minimum play rate in the current speed format, either as percentage or in 
frames-per-second. 

IMMSpeed Supported On: 

minimumSpeed( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


—Returns the device's normal play rate in the current speed format, either as a 
percentage or in frames-per-second. 


IMMSpeed 

normal Speed( Cal 

Supported On: 

Hype call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


—Returns the device's slow playback rate in the current speed format, either as a 
percentage or in frames-per-second. Returns 0 if the device cannot play slow. 

IMMSpeed Supported On: 

slowSpeed( CallType call = wait) const; PM 


© IBM Corp. 1992, 1995 


IMMDigitalVideo 919 






IMMDigitalV ideo 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Returns the currently set speed for the device. 


IMMSpeed 

speed( CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Record and Monitoring 

Use these members to record from a video capture card, monitor the video signal, and change the 
monitor window. 

disableMonitoring 

Sets monitoring of the incoming video signal off. When monitoring is turned on, a 
monitor window is created. When the monitor window is active and recording is not 
in progress, the monitor window displays the entire video source image, regardless of 
any source rectangle setting. During recording, only the area being captured is 
displayed. 

Monitoring during real-time recording is supported but at a reduced performance. 
Monitoring can not be turned on or off during recording, that is, if it is on when 
recording starts it must remain on while recording is in progress. Attempting to turn 
monitoring on or off during real-time recording results in an exception. 

During monitoring, audio is passed through and heard on the speakers or headphones 
connected to the sound card, if present. 
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virtual IMMDigitalVideo& Supported On: 

disableMonitoring( Call Type call = wait); PM 

enableMonitoring 

Sets monitoring of the incoming video signal on or off. When monitoring is turned 
on, a monitor window is created. When the monitor window is active and recording 
is not in progress, the monitor window displays the entire video source image, 
regardless of any source rectangle setting. During recording, only the area being 
captured is displayed. 

Monitoring during real-time recording is supported but at a reduced performance. 
Monitoring can not be turned on or off during recording, that is, if it is on when 
recording starts it must remain on while recording is in progress. Attempting to turn 
monitoring on or off during real-time recording results in an exception. 

During monitoring, audio is passed through and heard on the speakers or headphones 
connected to the sound card, if present. 

virtual IMMDigi tal Vi deo& Supported On: 

enableMonitoring( Boolean enable = true, PM 

Cal 1 Type cal 1 = wait); 


isMonitoring Enabled 

Returns true if monitoring of the incoming video signal is enabled. 

Boolean Supported On: 

isMonitoringEnabled( CallType call = wait) const; PM 


monitorHandle 

Returns the window handle for the current video monitor window. 

IWi ndowHandl e Supported On: 

monitorHandle( CallType call = wait) const; PM 

..Starts recording till it reaches the end location. If there was anything previously 
recorded it is deleted before the recording starts. If the end location is not specified, 
recording continues until a pause or stop occurs. It is recommended that you 
temporarily acquire the device exclusively while you are recording; otherwise, the 
recording can become inactive if another device requests access to the device. 
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virtual IMMDigi tal Video& Supported On: 

record( const IMMTime& end = IMMTime ( ), PM 

Boolean resumelfPaused = true, 

CallType call = nowait); 


setMonitorWindow 

Use this function to supply your own window where you can see the incoming video 
signal if monitoring is enabled. For example, you might want your monitor window 
in a canvas. If so, pass the handle of the canvas to this function. By default, the 
IMMDigitalVideo class creates and use its own video monitor window. This function 
allows an application to provide its own video monitor window. To switch back to 
using the default video monitor window, call useDefaultMonitorWindow (p. 922). 


[J IMMDi gi tal Vi deo& 

setMonitorWindow( const IWindowHandle& handle. 
Cal 1 Type cal 1 = wait); 


Supported On: 

PM 


| IMMDigitalVideo& 

setMonitorWindow( const IWindow& window. 
Cal 1 Type cal 1 “ wait); 


Supported On: 

PM 


useDefaultMonitorWindow 

Specifies that the digital video class creates and manages its own video monitor 
window. You can use it to set the video monitor window back to the default video 
monitor window. 


IMMDigitalVideo& 

useDefaultMonitorWindow( CallType call = wait); 


Supported On: 

PM 


Video Window 

These members are used to change the video window attributes and to play the loaded video at a 
different rate than normal. 


destinationRectangie 

Returns the subrectangle within the video window where video is played. This allows 
an application to move, grow, or shrink where the video is played inside the video 
window. 

IRectangle Supported On: 

destinationRectangle( CallType call = wait) const; PM 
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Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

Returns the window handle for the current video playback window. 

IWindowHandl e 
handle( CallType 

Supported On: 

call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


maximumWindows 

Returns the maximum number of video windows allowed on this machine. 

unsigned long Supported On: 

maximumWindows( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Restores the video window by causing the video device to transfer an image from 
the video to the playback window. This is similar to a refresh of a normal window. 
If the source rectangle is not specified, the entire image is restored. If the 
destination rectangle is not specified, the destination size is set to the same as the 
image size. If the destination rectangle is a different size than the source rectangle. 
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it tries to scale the image (if supported); otherwise, it clips the image to the 
destination rectangle. 

IMMDigitalVideo& 

refresh( const IRectangle& source = IRectangle ( ), 

const IRectangle& destination = IRectangle ( ), 

Cal Hype cal 1 = wai t); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid rectangle was specified. 


Supported On: 

PM 


set Destination 

Sets the subrectangle within the video window where video is played. This allows an 
application to move, grow, or shrink where the video is played inside the video 
window. 


IMMDi gi tal Vi deo& Supported On: 

setDestination( const IRectangle& rectangle, PM 

Cal 1 Type = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid rectangle was specified. 


_Use this function to supply your own window where the video is played. For 
example, you might want your video to be played back in a canvas. If so, pass the 
handle of the canvas to this function. By default, the IMMDigitalVideo class creates 
and use its own video window. This function allows an application to provide its 
own video playback window. To switch back to using the default video window, call 
useDefaultWindow (p. 926). 
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Q IMMDi gi tal Vi deo& Supported On: 

setWindow( const IWindowHandle& handle, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 


IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid window handle was specified. 


IMMDigitalVideo& 

setWindow( const IWindow& window, 

Cal 1 Type cal 1 = wait); 

Supported On: 

PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 


IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid window was specified. 



sourceRectangle 

Returns the subrectangle of the video from the currently loaded video file. 

IRectangle Supported On: 

sourceRectangle( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 
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useDefaultWindow 

Specifies that the digital video class creates and manages its own video window. You 
can use it to set the video window back to the default video window. 

IMMDi gi tal Vi deo& Supported On: 

useDefaul tWindow( Call Type call = wait); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


videoFileHeight 

Returns the height of the video for the currently loaded video file. 


unsigned long Supported On: 

videoFileHeight( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


videoFileName 

Returns the file name of the digital video file. 


IString Supported On: 

videoFileName() const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 
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videoFileWidth 


Exceptions 

IlnvalidRequest 

The device must be in the open state before calling this function. 

Returns the width of the video for the currently loaded video file. 

unsigned long 
videoFi 1 eWidth ( 

Supported On: 

CallType call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

.Returns the nominal (reasonable) height of the video for this machine. So, this 

would probably return a smaller value on a '386 machine than a '486 machine. 

unsigned long 
videoHeight( Cal 

Supported On: 

Hype call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


.Returns the nominal (reasonable) width of the video for this machine. So, this 

would probably return a smaller value on a '386 machine than a '486 machine. 

unsigned long Supported On: 

videoWidth( Call Type call = wait) const; PM 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 


IlnvalidRequest 

The device must be in the open state before calling this function. 


Inherited Public Functions 


IMMConfigurableAudio 

bitsPerS ample 

format 

setBytesPerSecond 

blockAlignment 

samplesPerSecond 

setChannels 

bytesPerSecond 

setB itsPerS ample 

setFormat 

channels 

setBlockAlignment 

setSamplesPerSecond 


IMMRecordable 

canRedo 

cut 

redo 

canUndo 

deleteSelection 

save 

copy 

paste 

saveAs 

cueForRecording 

record 

undo 


IMMFileMedia 

filename 

isReadOnly 

load 


IMMPIayableDevice 

addCuePoint 

position 

seekToStart 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 
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IMMDevice 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports V olume Adj ustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMDigitalVideo 
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IMMDigital Video( unsigned long deviceldenti fier. Supported On: 

const IString& newAlias); PM 

A derived class can construct an IMMDigitalVideo from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Implementation 

These members validate the open string, translate the audio flags, and play the video file using 
the passed in speed and range. 


isOpenStringValid 

Returns true if the passed in open string is valid for this device. 

virtual Boolean Supported On: 

isOpenStringVal id( const IString& deviceName) const; PM 

_ Allows the playing from a start to an end position with the specified flags and 
speed. If from is omitted, play starts at the current position; if to is omitted, play 
stops at the end of the video file. 


IMMDi gi tal Vi deo& Supported On: 

pi ayDi gi tal ( const IMMTime& from = IMMTime ( ), PM 

const IMMTime& to = IMMTime ( ), 

CallType call = nowait, 
unsigned long flags = 0, 
unsigned long speed = 0); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the video file. 
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translateAudioFlag 

Maps the wave audio commands to the digital video values. The digital video and 
the wave audio device both support setting the bytes-per-second, but the actual system 
values are different. By allowing the mapping of the wave audio values to the digital 
video values, the digital video player does not have to override all of the audio 
functions because they call this function. 

virtual unsigned long Supported On: 

translateAudioFlag( unsigned long) const; PM 


Inherited Protected Functions 


IMMConfigurableAudio 

translateAudioFlag 




IMMFileMedia 

setReadOnlyFlag 




IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Inherited Public Data 


IMMDevice 

allDevices 

cuePointld 

other 
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IMMDevice 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digitalVideo 

positionChangeld 

audioTape 

headphone 

sequencer 

cdxa 

microphone 

speaker 

commandNotifyld 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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I MM Error Info 


IBase 

IVBase 

IErrorlnfo 

IMMErrorlnfo 


_.None. 

_ immexcpt.hpp 


Member 

Page 

Member 

Page 

Constructor 

934 

text 

935 

errorld 

935 

throwMMError 

935 

isAvailable 

935 

'IMMErrorlnfo 

935 

operator const char * 

935 




Objects of the IMMErrorlnfo class represent error information that you can include in 
an exception object. When an multimedia call results in an error condition, objects of 
the IMMErrorlnfo class are created. You can use the error text to construct a derived 
class object of IException (Vol. I). 

The User Interface Class Library provides the following macros for throwing 
exceptions constructed with IMMErrorlnfo information. 

ITHROWMMERROR 

Accepts the following parameters: 

error The multimedia error number. 
functionName 

The name of the multimedia function that returned an error 
condition. 

This macro then generates code that calls IMMErrorlnfo::throwMMError (p. 
935), which does the following: 

1. Creates an IMMErrorlnfo object 

2. Uses the object to create an object of IAccessError (Vol. I) 

3. Adds location information 

4. Logs the exception data 

5. Throws the exception 
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Note: This macro uses the recoverable enumerator provided by 
IException::Severity (Vol. I). 

ITHROWMMERROR2 

Throws any of the User Interface Class Library-defined exceptions. This macro 

accepts the following parameters: 

error The multimedia error number. 

location The name of the multimedia function returning an error code, the 
name of the file the function is in, and the function’s line number. 

type Use the enumeration IErrorInfo::ExceptionType (Vol. I) to specify 

the type of the exception. The User Interface Class Library uses 
accessError as the default type on its exceptions. 

severity Use the enumeration IException::Severity (Vol. I) to specify the 
severity of the error. The User Interface Class Library uses 
recoverable as the default severity on its exceptions. 

This macro generates code that calls throwMMError (p. 935), which does the 

following: 

1. Creates an IMMErrorlnfo object 

2. Uses the object to create an Exception object 

3. Adds location information 

4. Logs the exception data 

5. Throws the exception 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot create copies of objects of this 
class. 


__ There is only one way to construct instances of this class. If the error number and 
the name of the failing API is passed in, it will be prefixed to the error text. If the 
error text cannot be loaded, the following default text is provided: "No error text is 
available." 

IMMErrorlnfo( unsigned long errorld = 0, Supported On: 

const char* functionName = 0); PM 
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"IMMErrorlnfo 


virtual 

"IMMErrorlnfoO ; 


Supported On: 

PM 


Error Information 

Use these members to query the accessible attributes of this class. 
Returns the error ID. 


virtual unsigned long Supported On: 

errorId() const; PM 

_If there is error text available for the error, returns true. 


virtual Boolean Supported On: 

isAvai 1 able() const; PM 

_Returns the error text. 


virtual Supported On: 

operator const char *() const; PM 

Returns the error text. 


virtual const char* 
text() const; 


Supported On: 

PM 


Throw Support 

Use these members to support throwing of exceptions. The 1THROWMMERROR macro uses 
these members. 


throwMMError 

Creates an IMMErrorlnfo object and uses the text from it to do the following: 

1. Create an exception object 

2. Add the location information to it 

3. Log the exception data 

4. Throw the exception 

errorld The error number for the exception. 
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functionName 

The name of the function (probably a system function) that failed. 
location An IExceptionLocation (Vol. I) object containing the following: 

• Function name where the failure was detected and the exception 
thrown 

• File name 

• Fine number where the function is called 

name Use the enumeration IErrorInfo::ExceptionType (Vol. I) to specify the 
type of the exception. The default is accessError. 

severity Use the enumeration Exception::Severity (Vol. I) to specify the severity 
of the error. The default is recoverable. 


static void Supported On: 

throwMMError( unsigned long errorld, PM 

const char* functionName, 
const IExceptionLocation& location, 

IErrorlnfo::ExceptionType name = accessError, 

IException::Severity severity = recoverable); 


Inherited Public Functions 


IErrorlnfo 

errorld 

isAvailable 

operator const char * 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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I MM File Media 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMFileMedia 


IMMRecordable 

IMMSequencer 


_immfilem.hpp 


Member 

Page 

Member 

Page 

Constructor 

941 

loadOnThread 

939 

filename 

938 

setReadOnlyFlag 

942 

isReadOnly 

938 

“IMMFileMedia 

937 

load 

938 




The IMMFileMedia is the base class for devices that use files, and it provides 
functions for loading data from a file. 


Public Functions 
Constructors 

Derived classes can use these members to create objects of this class. 


"IMMFileMedia 


virtual 

"IMMFileMediaO ; 


Supported On: 

PM 


File Loading 

Use these members to load a file into the device and to query information about the currently 
loaded file, for example, the file name and if the file was loaded as read-only. 
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Returns the currently loaded file name. 


IString 

filename( Call Type call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file was not found; possibly there is no loaded file. 


—Returns true if the file was loaded as read-only; otherwise, false is returned. If the 
file was loaded as read-only, then the system prevents any changes to the file. The 
audio driver might also be able to improve load and runtime performance as no 
changes are allowed. Save and record functions throws an exception if the file was 
loaded as read-only. 

virtual Boolean Supported On: 

i sReadOnly() const; PM 

.Loads the given file into memory. If the file does not exist, a temporary file is 
created. Note, if call is wait (p. 901) , then the windowing system is tied up until 
the file is loaded. If you do not want to tie up of the windowing system and you do 
not want the load function to return until the file is loaded, use the loadOnThread 
(Vol. II) function. Otherwise, you could set call to nowait (p. 901) , which causes 
this function to return immediately. When the load finishes, an INotificationEvent 
(Vol. I) is sent to any observers that are attached to this device, notifying them that 
the load has finished. 

If the file is loaded as read-only, the system prevents any changes being made to the 
file. The audio driver might also be able to improve load and runtime performance as 
no changes are allowed. Save and record functions throw an exception if the file was 
loaded as read-only. 

virtual IMMFi 1 eMedia& Supported On: 

load( const IString& filename, PM 

Boolean readonly = false. 

Cal 1 Type cal 1 = wait); 
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Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file is not found. 

IAccessError 

Invalid media type or invalid data format. 

IAccessError 

A hardware error occurred. 

IAccessError 

A file Attribute error occurred. 

IAccessError 

This format is unsupported; possibly the hardware does not support the 
samples-per-second, the bits-per-sample, the number of channels, or the 
audio format. 


loadOnThread 

Loads the given file into memory by creating a thread to do the actual loading. By 
doing the loading this way, it does not tie up the windowing system. This function 
does not return until the file is loaded. If the file does not exist, a temporary file is 
created. 

If the file is loaded as read-only, the system prevents any changes being made to the 
file. The audio driver might also be able to improve load and runtime performance as 
no changes are allowed. Save and record functions throw an exception if the file was 
loaded as read-only. 


virtual IMMFi 1 eMedia& Supported On: 

loadOnThread( const IString& filename, PM 

Boolean readonly = false); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file is not found. 

IAccessError 

Invalid media type or invalid data format. 

IAccessError 

A hardware error occurred. 

IAccessError 

A file Attribute error occurred. 
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Exceptions 

IAccessError This format is unsupported; possibly the hardware does not support the 

samples-per-second, the bits-per-sample, the number of channels, or the 
audio format. 


Inherited Public Functions 


IMMPlayableDevice 

addCuePoint 

position 

seekToStart 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports V olume Adj ustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

setVolume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 
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Protected Functions 
Constructors 

Derived classes can use these members to create objects of this class. 

IMMFileMedia 

| IMMF1TeMedia( const IString& deviceName, 

Boolean openNow, 
unsigned long instance. 

Boolean openShareable); 

A derived class can construct an IMMFileMedia from the following: 

deviceName 

You must specify what device you wish to construct. 

openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 

instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 

§ IMMFileMedia( unsigned long deviceldentifier, Supported On: 

const IString& newAlias = IString ( )); PM 


Supported On: 

PM 
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A derived class can construct an IMMFileMedia from the following: 
deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Implementation 

These members change the read-only state of the flag for the loaded file. 


setReadOnlyFlag 

Allows the device to track read-only status of the loaded file. 


virtual IMMFi1eMedia& 
setReadOnlyFlag( Boolean readonly); 


Supported On: 

PM 


Inherited Protected Functions 


IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setUserParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Inherited Public Data 


IMMDevice 

allDevices 

euePointld 

other 

ampMixer 

dat 

overlay 
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IMMDevice 

animation 

deviceEventld 

passDeviceld 

audioCD 

digital Video 

positionChangeld 

audioTape 

headphone 

sequencer 

cdxa 

microphone 

speaker 

commandN otify Id 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMHourMinSecFrameTime 


IBase 

IVBase 

IMMTime 

IMMHourMinSecFrameTime 


IMM 24Frame sPerS econdTime 
IMM25 Frame sPerS econdTime 
IMM30FramesPerSecondTime 


_nmmtime.hpp 


Member 

Page 

Constructor 

945 

asString 

946 

frames 

944 

framesPerSecond 

944 

hours 

945 

minutes 

945 


Member 

Page 

operator unsigned long 

946 

ordinal 

946 

seconds 

945 

setTimeToOrdinal 

947 

'IMMHourMinSecFrameTime 

946 


The IMMHourMinSecFrameTime data type class represents the 
hours-minutes-seconds-frames (HHMMSSFF) time format. 


Public Functions 
Attributes 

Use these functions to parse the time into normal time values, for example, hours, minutes, and 
seconds. 


Returns the frames component of the time. 


virtual unsigned long Supported On: 

frames() const; PM 

framesPerSecond 

Returns the number of frames per second. 
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unsigned long Supported On: 

framesPerSecond() const; PM 

Returns the hours component of the time. 


virtual unsigned long Supported On: 

hours() const; PM 

Returns the minutes component of the time. This is in the range of 0 to 59. 


virtual unsigned long Supported On: 

minutesO const; PM 

Returns the seconds component of the time. This is in the range of 0 to 59. 


virtual unsigned long 
seconds() const; 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. 

IMMHourMinSecFrameTime 

|1 IMMHourMinSecFrameTime( const IMMHourMinSecFrameTime& time); Supported On: 

PM 


g IMMHourMinSecFrameTime( unsigned long value = defaultTime, Supported On: 

unsigned long framesPerSecond = 1); PM 

You can construct an IMMHourMinSecFrameTime from: 

value A time value(FFSSMMHH) where: 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

framesPerSecond 

The number of frames that occur for each second. 
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IMMHourMinSecFrameTime 


virtual 

'IMMHourMinSecFrameTimeO; 


Supported On: 

PM 


Conversions 

Use these members to cast the time to an unsigned long. 

_Returns the time as a unsigned long in the following format (FFSSMMHH): 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

virtual Supported On: 

operator unsigned 1 ong() const; PM 


Diagnostics 

Use these members to return the time as a string. 

_Returns the time value as a string formatted as HH:MM:SS.FF. 


virtual IString 
asString() const; 


Supported On: 

PM 


Ordinal 

Use these ordinal number functions for indicating generic positions. A time object returns an 
ordinal number, which represents the time at some particular granularity. This is useful for 
something that allows seeking and displays position, such as a slider. Because sliders generally 
do not process time values, you use an ordinal number to establish the range of slider values. 
Ordinals numbers can be mathematically manipulated and converted back to time values, if 
necessary. 

Note: Some time values are difficult to represent as an ordinal value, such as 

IMMTrackMinSecFrameTime. Such a time object produces ordinal numbers that are 
dependent on unknown information, such as the table of contents of a CD. Some time 
classes might not be able to correctly implement setTimeToOrdinal (p. 947). 

Returns an ordinal number in frames. This is the time converted to the total number 
of frames based on the number of frames per second. 
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virtual unsigned long Supported On: 

ordinal () const; PM 

setTimeToOrdinal 

Sets the time object to the value represented by the ordinal number (in frames). This 
uses the current number of frames-per-second to convert this value. 


virtual IMMTime& 

setTimeToOrdinal( unsigned long ordinal); 


Supported On: 

PM 


Inherited Public Functions 


IMMTime 

asMMTirae 

operator + 

operator == 

asString 

operator += 

operator > 

hours 

operator - 

operator >= 

hundredths 

operator -= 

operator unsigned long 

is Valid 

operator < 

ordinal 

minutes 

operator <= 

seconds 

operator != 

operator = 

setTimeToOrdinal 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMTime 

setMMTime 

set Valid 
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Inherited Public Data 



Inherited Protected Data 
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IMMHourMinSecTime 


IBase 

IVBase 

IMMTime 

IMMHourMinSecTime 


_.None. 


_.immtime.hpp 


Member 

Page 

Constructor 

950 

asString 

951 

hours 

949 

minutes 

949 

operator unsigned long 

950 


Member 

Page 

ordinal 

951 

seconds 

949 

setTimeToOrdinal 

951 

'IMMHourMinSecTime 

950 


The IMMHourMinSecTime datatype class represents the hours-minutes-seconds 
(HHMMSS) time format. 


Public Functions 
Attributes 

Use these functions to parse the time into normal time values, for example, hours, minutes and 
seconds. 


Returns the hours component of the time. 


virtual unsigned long Supported On: 

hours() const; PM 

Returns the minutes component of the time. This is in the range of 0 to 59. 


virtual unsigned long Supported On: 

minutesO const; PM 

Returns the seconds component of the time. This is in the range of 0 to 59. 
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virtual unsigned long 
seconds() const; 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. 


IMMHourMinSecTime 

| IMMHourMinSecTime( unsigned long value = defaultTime); Supported On: 

PM 


You can construct an IMMHourMinSecTime from: 
value A time value where: 

1. 1st byte is reservedfand not used) 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 

Q IMMHourMinSecTime( const IMMHourMinSecTime& time); Supported On: 

PM 


0 IMMHourMinSecTime( const IMMTime& time); Supported On: 

PM 

IMMHourMinSecTime 

virtual Supported On: 

'IMMHourMinSecTimeO; PM 


Conversions 

Use these members to cast the time to an unsigned long. 

_Returns the time as a unsigned long in the following format (RRSSMMHH): 

1. 1st byte is reserved 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the hours 
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virtual 

operator unsigned long() const; 


Supported On: 

PM 


Diagnostics 

Use these members to return the time as a string. 

_Returns the time value as a string formatted as HH:MM:SS. 


virtual IString 
asString() const; 


Supported On: 

PM 


Ordinal 

Use these ordinal number functions for indicating generic positions. A time object returns an 
ordinal number, which represents the time at some particular granularity. This is useful for 
something that allows seeking and displays position, such as a slider. Because sliders generally 
do not process time values, use an ordinal number to establish the range of slider values. 
Ordinal numbers can be mathematically manipulated and converted back to time values, if 
necessary. 

Note: Some time values are difficult to represent as an ordinal value, such as 

IMMTrackMinSecFrameTime. Such a time object produces ordinal numbers that are 
dependent on unknown information, such as the table of contents of a CD. Some time 
classes might not be able to correctly implement setTimeToOrdinal (p. 951). 

Returns the time value in total seconds. 

virtual unsigned long 
ordinal() const; 

setTimeToOrdinal 

Sets the time object to the value represented by the ordinal number (in seconds). 

virtual IMMTime& Supported On: 

setTimeToOrdinal ( unsigned long ordinal); PM 


Supported On: 

PM 


Inherited Public Functions 


IMMTime 

asMMTirae 

operator + 

operator == 

asString 

operator += 

operator > 
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IMMTime 

hours 

operator - 

operator >= 

hundredths 

operator -= 

operator unsigned long 

is Valid 

operator < 

ordinal 

minutes 

operator <= 

seconds 

operator != 

operator = 

setTimeToOrdinal 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMTime 

setMMTime 

setValid 



Inherited Public Data 


IMMTime 

defaultTime 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMMasterAudio 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMMasterAudio 


—None. 

—immmaud.hpp 


Member Page 

Constructor 953 

areHeadphonesEnabled 954 

areSpeakersEnabled 955 

disableHeadphones 954 

disableSpeakers 955 

enableHeadphones 954 

enableSpeakers 955 


Member 

Page 

saveHeadphonesSetting 

954 

saveSpeakersSetting 

955 

saveVolume 

955 

setVolume 

955 

volume 

956 

'IMMMasterAudio 

954 


The IMMMasterAudio class provides behavior for modifying the master audio 
settings for all audio devices in the system. The application can set, query and save 
the headphones', speakers', and master volume settings for the system. When any of 
the multimedia devices are opened, they query the master audio settings and 
automatically adjust their settings accordingly. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMMasterAudio 


IMMMasterAudio(); 


Supported On: 

PM 
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IMMMasterAudio 


virtual 

"TMMMasterAudio(); 


Headphones 

Use these members to set, query, and save the headphones' setting. 


areHeadphonesEnabled 

Returns if the headphones' setting is enabled for the passed in 
current setting or the saved setting); otherwise, returns false. 


Boolean 

areHeadphonesEnabled( 

SettingSource source = current, 

IMMDevice::Cal1 Type call = IMMDevice::wait) const; 


disableHeadphones 

Turns the headphones' settings off. 


virtual IMMMasterAudio& 
disableHeadphones( 

IMMDevice::Cal1 Type call = IMMDevice::wait); 


enableHeadphones 

Turns the headphones' settings either off or on. 


virtual IMMMasterAudio& 
enableHeadphones ( 

Boolean enable = true, 

IMMDevice::Cal1 Type call = IMMDevice::wait); 


saveHeadphonesSetting 

Saves the current headphones' setting of the operating system. 


virtual IMMMasterAudio& 
saveHeadphonesSetting( 

IMMDevice::Cal1 Type call = IMMDevice::wait); 


Supported On: 

PM 


source (either the 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


954 Open Class Library Reference 



IMMMaster Audio 


Speakers 

Use these members to set, query, and save the speakers' setting. 


areSpeakersEnabled 

Returns the true if the speakers' setting is enabled for the passed in 
current setting or the saved setting); otherwise, returns false. 


Boolean 

areSpeakersEnabled( 

SettingSource source = current, 

IMMDevice:: Cal Hype call = IMMDevi ce: :wai t) const; 


disableSpeakers 

Turns the speakers' setting off. 


virtual IMMMasterAudio& 
disableSpeakers( 

IMMDevice:: Cal Hype call = IMMDevi ce: :wai t); 


enableSpeakers 

Turns the speakers' setting either on or off. 


virtual IMMMasterAudio& 
enableSpeakers( Boolean enable = true, 

IMMDevice:: Cal Hype call = IMMDevi ce: :wai t); 


saveSpeakersSetting 

Saves the current speakers' setting of the operating system. 


virtual IMMMasterAudio& 
saveSpeakersSetting( 

IMMDevice:: Cal Hype call = IMMDevi ce: :wai t); 


Volume 

Use these members to set, query, and save the master volume setting. 

— Saves the current master volume setting of the operating system. 


virtual IMMMasterAudio& 

saveVolume( IMMDevice:: Ca 1 Hype call = IMMDevi ce: :wai t); 
-Sets the master volume for the operating system. 


source (either the 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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virtual IMMMasterAudio& 
setVolume( unsigned long volume, 

IMMDevice::Cal1 Type call = IMMDevice::wait); 


Supported On: 

PM 


Returns the master volume setting for either the current setting or the saved setting 
to a percent of the maximum audio level. 


unsigned long 

volume( SettingSource source = current, 

IMMDevice::CalIType call = IMMDevice::wait) const; 


Supported On: 

PM 


Inherited Public Functions 


IStandardNotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 
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Inherited Public Data 



Inherited Protected Data 



SettingSource 

SettingSource { 

saved = 0X00004000L, 
current = 0xO00O80OOL 
}; 

Enumeration that specifies which setting to query and set. 
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IM MM i I lisecondTi me 


IBase 

IVBase 

IMMTime 

IMMMillisecondTime 


_.None. 

_jmmtime.hpp 

Member Page 

Constructor 958 

operator unsigned long 959 

'IMMMillisecondTime 959 


The IMMMillisecondTime data type class represents one-thousandth of a second. 


Public Functions 


Constructors 

You can construct and destruct objects of this class. 


IMMMillisecondTime 


| IMMMillisecondTime( unsigned long time = defaultTime); 


Supported On: 

PM 


| IMMMillisecondTime( const IMMMi11isecondTime& time); 


Supported On: 

PM 


2 IMMMi11isecondTime( const IMMTime& time); 


Supported On: 

PM 
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IMMMillisecondTime 


virtual 

"IMMMillisecondTimeO ; 


Supported On: 

PM 


Conversions 

Use these members to cast the time to an unsigned long. 

_Returns the time as an unsigned long where each time unit is equal to 

one-thousandth of a second. 


virtual 

operator unsigned long() const; 


Supported On: 

PM 


Inherited Public Functions 


IMMTime 

asMMTirae 

operator + 

operator == 

asString 

operator += 

operator > 

hours 

operator - 

operator >= 

hundredths 

operator -= 

operator unsigned long 

is Valid 

operator < 

ordinal 

minutes 

operator <= 

seconds 

operator != 

operator = 

setTimeToOrdinal 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMTime 

setMMTime 

set Valid 
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Inherited Public Data 



Inherited Protected Data 
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IMMMinSecFrameTime 


IBase 

IVBase 

IMMTime 

IMMMinSecFrameTime 


_.None. 

_immtime.hpp 


Member 

Page 

Member 

Page 

Constructor 

962 

operator unsigned long 

962 

asString 

963 

seconds 

961 

frames 

961 

~IMMMin S ecFrameTime 

962 

minutes 

961 




The IMMMinSecFrameTime data type class represents the time format based on the 
75-frames-per-second CD digital audio standard. 


Public Functions 
Attributes 

Use these members to parse the time into normal time values, for example, hours and minutes. 
Returns the frames component of the time. 


unsigned long Supported On: 

frames() const; PM 

Returns the minutes component of the time. This is in the range of 0 to 59. 


unsigned long Supported On: 

minutesO const; PM 

Returns the seconds component of the time. This is in the range of 0 to 59. 


unsigned long 
seconds() const; 


Supported On: 

PM 
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Constructors 

You can construct and destruct objects of this class. 

IMMMinSecFrameTime 

| IMMMinSecFrameTime! const IMMMinSecFrameTime& time); Supported On: 

PM 


| IMMMinSecFrameTime! unsigned long value = defaul tTime); Supported On: 

PM 


You can construct an IMMMinSecFrameTime from: 
value A time value where: 

1. 1st byte is the reserved! not used) 

2. 2nd byte is the frames 

3. 3rd byte is the seconds 

4. 4th byte is the minutes 

0 IMMMinSecFrameTime! const IMMTime& time); Supported On: 

PM 

IMMMinSecFrameTime 


virtual 

"TMMMinSecFrameTimeO; 


Supported On: 

PM 


Conversions 

Use these members to cast the time to an unsigned long. 

_Returns the time as a unsigned long in the following format (RRFFSSMM): 

1. 1st byte is reserved 

2. 2nd byte is the frames 

3. 3rd byte is the seconds 

4. 4th byte is the minutes 

virtual Supported On: 

operator unsigned 1 ong() const; PM 
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Diagnostics 

Use these members to return the time as a string. 

_Returns the time value as a string formatted as MM:SS.FF. 


virtual IString 
asString() const; 


Supported On: 

PM 


Inherited Public Functions 


IMMTime 

asMMTirae 

operator + 

operator == 

asString 

operator += 

operator > 

hours 

operator - 

operator >= 

hundredths 

operator -= 

operator unsigned long 

is Valid 

operator < 

ordinal 

minutes 

operator <= 

seconds 

operator != 

operator = 

setTimeToOrdinal 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMTime 

setMMTime 

set Valid 



Inherited Public Data 


IMMTime 

defaultTime 
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IMMNotifyEvent 


IBase 

IVBase 

IEvent 

IMMNotifyEvent 


_.None. 


_-immevt.hpp 


Member 

Page 

Constructor 

966 

command 

965 

device 

966 

errorld 

966 


Member 

Page 

errorText 

966 

successCode 

967 

userParameter 

966 

~IMMN otify Event 

966 


The IMMNotifyEvent class is the class for notification events. These events get 
generated when any device function gets called. This can be powerful for 
asynchronous processing when you do not want to wait for something to finish. For 
more information, see IMMDevice: :nowait (p. 901). To get notified of events, you 
attach an observer to the device and it sends a notification when a command has 
finished processing. From this event, you can find out what command was called, 
from which device it came, the return value of the command that was executed, and, 
if the command generated an error, what its error number and string are. 


Public Functions 
Command 

Use these members to determine what command generated this notification. 

-Returns the command that generated this notification event. 

Command Supported On: 

command() const; PM 
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Constructors 

You can construct and destruct objects of this class. 

IMMNotifyEvent 

Although you can construct objects of this class, typically 

IMMDeviceHandler::dispatchHandlerEvent (p. 910) creates objects of this class from 
an object of the class IEvent (Vol. II) or another IMMNotifyEvent object. 

IMMNotifyEvent) const IEvent& event); Supported On: 

PM 


"IMMNotifyEvent 

virtual 

'IMMNotifyEvent (); 


Supported On: 

PM 


Event Information 

Use these members to parse the event information into the success state of the command (and, if 
there is an error, its error code and string) and to access the user parameter. 

Returns a pointer to the device that this event is from. 

IMMDevi ce* Supported On: 

device)) const; PM 

Returns the error code from the command if there was one; otherwise, it returns 0. 


unsigned short Supported On: 

errorld)) const; PM 

Returns the error text for a given error code. If there was not any error text, then it 
returns a null IString. 


static IString 

errorText) unsigned long errorCode); 


Supported On: 

PM 


userParameter 

Returns the user parameter that was set at the time of this event. See 
IMMDevice::setUserParameter (p. 895) for more information. 


966 Open Class Library Reference 



IMMNotifyEvent 


unsigned short 
userParameter() const; 


Supported On: 

PM 


Success Code 

Use these members to determine if the command succeeded. 

—Returns the success code, which indicates if the command succeeded or failed. 


SuccessCode 

successCode() const; 


Supported On: 

PM 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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SuccessCode 


SuccessCode { 
successful, 
preempted, 
aborted, 
error 
}; 


Enumeration that specifies if the command was successful. The following are valid 
values: 

successful 

The command was completed successfully. 

preempted 

Another notification request (same type of command) was received. 

aborted 

The command was interrupted and is unable to be completed. For example, the 
first command was a play with nowait, and a second command, stop, was 
issued before the play could finish. 


error 

The command caused an error to occur. 


Command { 
open = 1, 

Play, 

pause, 

status, 

step, 

save, 

setCuePoint, 

load, 

masterAudio, 
connector, 
defaultConnection, 
capture = 40, 
getlmagePalette, 
rewind, 

setlmagePalette, 
windowCommand, 
paste, 
undo 
}; 


close, 

seek, 

info, 

spin, 

record, 

cue, 

setPositionAdvise, 

acquireDevice, 

getTableOfContents, 

resume, 

connection, 

freeze, 

put, 

restore, 
unfreeze, 
deleteCommand, 
copy. 


escape, 

stop, 

getDeviceCapabi1ities, 
set, 

syslnfo, 

update, 

setSyncOffset, 
releaseDevice, 
deviceSettings, 
connectorlnfo, 
group, 

getlmageBuffer, 

realize, 

setlmageBuffer, 

where, 

cut, 

redo. 


Enumeration that specifies the command that this event was generated for. 
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IMMPassDeviceEvent 


IBase 

IVBase 

IEvent 

IMMPassDeviceEvent 


_.None. 


_ immevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

969 

isGainingUse 

970 

device 

970 

'IMMPassDeviceEvent 

969 


The IMMPassDeviceEvent class is the class for pass device events. These events get 
generated when a device is being requested to release a shared hardware device (such 
as a CD-ROM drive). 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMPassDeviceEvent 

Although you can construct objects of this class, typically 

IMMDeviceHandler::dispatchHandlerEvent (p. 910) creates objects of this class from 
an object of the class IEvent (Vol. II) or another IMMPassDeviceEvent object. 

IMMPassDeviceEvent( const IEvent& event); Supported On: 

PM 


IMMPassDeviceEvent 

virtual 

'IMMPassDeviceEvent(); 


Supported On: 

PM 
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Event Information 

Use these members to parse the event into the ID of the device that is either losing or gaining 
use of the hardware device. 

Returns a pointer to the device that is being requested to lose use of or gain use of a 
device. See isGainingUse (p. 970) to find out what this device is being requested to 
do. 

IMMDevice* Supported On: 

device() const; PM 

Returns true if the device is gaining use of the hardware device and returns false if 
it is losing use of the device. 

Bool ean Supported On: 

isGainingUse() const; PM 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMPlayableDevice 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 


IMMFileMedia 

IMMRemovableMedia 


_Jmmplayd.hpp 


Member 

Page 

Constructor 

980 

addCuePoint 

972 

cueForPlayback 

976 

length 

973 

pause 

975 

play 

976 

position 

974 

removeCuePoint 

973 

resume 

975 


Member 

Page 

seek 

978 

seekToEnd 

978 

seekToStart 

978 

startPositionTracking 

974 

stepFrame 

979 

stop 

977 

stopPositionTracking 

975 

“IMMPlayableDevice 

977 


The IMMPlayableDevice is the base class for playable devices. It provides all of the 
common base functions for play, pause, stop, and similar functions. There are 
functions for querying and moving the current position and for turning on notification 
to observers of position changes. 


Public Functions 
Cue Points 

Use these members to add and remove cue points. 

_.Sets a cue point at the given location. A cue point is a location or time position in 
a media device. When a device encounters (by playing or recording) a time position 
associated with a cue point, a IMMCuePointEvent (p. 870) is generated. 


972 Open Class Library Reference 







IMMPlayableDevice 


virtual IMMP1 ayableDevice& Supported On: 

addCuePoint( const IMMTime& time, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The time is an invalid time value. 


removeCuePoint 

Removes the given cue point. A cue point is a location or time position in a media 
device. When a device encounters (by playing or recording) a time position 
associated with a cue point, a IMMCuePointEvent (p. 870) is generated. 


virtual IMMP1ayableDevice& 

removeCuePoint( const IMMTime& time, 
Cal Hype cal 1 = wai t); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The time is an invalid value; possibly the time value does not have a cue 
point set at its location. 


Notifications 

Use start and stop position tracking members to cause position change events to be generated. 
Use the length function to determine the amount of data and the position function to find out 
where you are in the data. 

Returns the total length in the current time format as an unsigned long. Use this 
value to create a time object in the current time format. 


unsigned long 

length( CallType call = wait) const; 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

Returns the current position in the current time format as an unsigned long. Use this 
value to create a time object in the current time format. 

unsigned long 
position( Cal' 

Supported On: 

IType call = wait) const; PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


startPositionT racking 

Starts position tracking. Position tracking causes a position change event to be 
generated every time the position of the media changes the passed in timelnterval. 


virtual IMMP1 ayableDevice& Supported On: 

startPositionTracking( const IMMTime& timelnterval, PM 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file is not found; possibly no file is currently loaded. 

IAccessError 

The timelnterval is out of range; possibly the time value is past the length 
of the data. 
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stopPositionT racking 

Stops position tracking. Position tracking causes a position change event to be 
generated every time the position of the media changes a given time amount. 

virtual IMMP1 ayableDevice& Supported On: 

stopPositionTracking( CallType call = wait); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Pause and Resume 

Use these members to pause and resume playback. 

If the device is playing, then it pauses the device. 


virtual IMMP1ayableDevice& 
pause( CallType call = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Resumes playback of the device from a paused state, if resume is true. The previous 
specified to parameter in the play (p. 976) function remains in effect. 


virtual IMMP1ayableDevice& 
resume( Boolean resume = true, 
CallType cal 1 = wait); 


Supported On: 

PM 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 


IlnvalidRequest 

The device must be in the open state before calling this function. 


Play and Stop 

Use these members to play or stop playback of the device. Use cueForPlayback to notify the 
device that you are going to start to play the device. 

cueForPlayback 

Cues the device for playback. This function does not have to be issued before 
playback; however, depending on the device, it might reduce the delay associated 
with the play function. For example, you might have a compact disc player that stops 
the spinning of the CD, when it isn't playing. This function might cause the CD to 
start spinning, thereby reducing the time before the CD starts the playback. 


virtual IMMP1 ayableDevice& Supported On: 

cueForPl ayback( Call Type call = wait); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There is no data present; possibly no file is loaded or no media is in the 
device. 


.Starts playing the device from the passed in start position to the passed in end 
position. If from is omitted, the device starts playing at the current position; if to is 
omitted, play stops at the end of the data. If resumelfPciused is true and the device is 
paused, it resumes playback of the device; otherwise, it starts playback from the 
passed in start position. 
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virtual IMMP1ayableDevice& 
play( const IMMTime& from = IMMTime ( 
const IMMTime& to = IMMTime ( ) 
Boolean resumelfPaused = true, 
Call Type call = nowait); 


Supported On: 

). PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IlnvalidRequest 

There is no data present; possibly no file is loaded or no media is in the 
device. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the data. 


Stops playback of the device. 


virtual IMMP1ayableDevice& 
stop( CallType call = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Protected Constructors 

Derived classes can use these functions to create objects of the IMMPlayableDevice class. 


IMMPlayableDevice 


virtual 

"IMMP1ayableDevice(); 


Supported On: 

PM 
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Seek 

Use these members to seek (move the current position) to either the beginning or the ending of 
the data or to a particular location in the data. Also, you can use the step frame member to 
move a single frame forward or backward. 

..Sets the current position of the device to the passed in position. 


virtual IMMP1ayableDevice& 
seek( const IMMTime& to. 

Cal 1 Type cal 1 = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file is not found; possibly no file is currently loaded. 

IAccessError 

The current device does not support the ability to seek. 

IAccessError 

The to position is out of range; possibly it is beyond the end of the media. 


-Moves the current position to the end of the data in the device. 


virtual IMMP1ayableDevice& 
seekToEnd( CallType call = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file is not found; possibly no file is currently loaded. 

IAccessError 

The current device does not support the ability to seek. 


—Moves the current position to the start of the data in the device. 
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virtual IMMP1ayableDevice& 

seekToStart( CallType call = wait); 


Supported On: 

PM 


Exceptions 


IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file is not found; possibly no file is currently loaded. 

IAccessError 

The current device does not support the ability to seek. 


_Steps the play one or more time units forward or backward. 

virtual IMMP1ayableDevice& 
stepFrame( unsigned long frames = 1, 

Boolean forward = true, 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

This is an unsupported function; possibly the device does not support the 
ability to step the player. 


Supported On: 

PM 


Inherited Public Functions 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 
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IMMDevice 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supports Save 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports Volume Adjustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Protected Constructors 

Derived classes can use these functions to create objects of the IMMPlayableDevice class. 


IMMPlayableDevice 

[J IMMPlayableDevice( const IString& deviceOrFi 1 eName, Supported On: 

Boolean openNow = true, PM 

unsigned long instance = 0, 

Boolean openShareable = true); 

A derived class can construct an IMMPlayableDevice from the following: 
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deviceOrFileName 

You must specify what type of playable device you wish to construct. 

openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 

instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 

| IMMPlayableDevice( unsigned long deviceldentifier. Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMPlayableDevice from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Inherited Protected Functions 


IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 
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Inherited Public Data 


IMMDevice 

allDevices 

cuePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digitalVideo 

positionChangeld 

audioTape 

headphone 

sequencer 

cdxa 

microphone 

speaker 

commandNotifyld 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMPlayerPanel 


IBase 

IVBase 

INotifier 

Window 

IControl 

ICanvas 

IMultiCellCanvas 

IMMPlayerPanel 


_.None. 


—immplypn.hpp 


Member 

Page 

Constructor 

985 

deviceType 

987 

fastForwardB utton 

984 

pauseButton 

984 

playableDevice 

987 

play Button 

985 


Member 

Page 

re windB utton 

985 

setPlayableDevice 

987 

stepBackwardB utton 

985 

stepForwardButton 

985 

stopButton 

985 

'IMMPlayerPanel 

986 


IMMPlayerPanel is a device player panel that contains various buttons for controlling 
the device. It can be constructed directly or inherited, if finer device control or more 
functionality is needed. The user is presented with a generic interface, sufficient to 
control most multimedia devices. 


nIJ 

41 

J J 

J 

> 


J/ 


Figure 10. Shows a IMMPlayerPanel with a device type of digitial video 

Not only does it create the buttons and organize them, but it also makes the actual 
function call for the button. For example, the play button calls the play function on 
whatever device is currently set into the player panel. Also, there is some intelligent 
processing for disabling and enabling the buttons. For example, if the device is 
stopped, the stop and pause buttons are disabled. Or, if the device is playing and the 
user presses the pause button, the pause button stays pressed in the down (latched) 
state and the play button is unlatched. If the user then presses the pause button again. 
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the pause button is unlatched and the play button is latched. The player panel 
automatically attaches an IMMPlayerPanelHandler (p. 990) object to provide default 
behavior. See IMMPlayerPanelHandler (p. 990) for more information on the default 
processing for each of the buttons and for how to change the default behavior. 

If you create the IMMPlayerPanel without passing in a device type, you get the 
default buttons, which are rewind, stop, pause, play, and fast forward. If you pass in 
overlay, videoDisc animation, or digitalVideo, you also get step forward and step 
backward buttons. 


IMMPlayerPanel is implemented using a set of buttons on an IMultiCellCanvas (p. 
1049). The canvas is set up with all of the default behavior and styles of the 
multiple-cell canvas, and none of the rows or columns is made expandable. The 
buttons are added to the multiple-cell canvas in the following coordinates. 


play 

pause 

fastForward 

rewind 

stop 

stepForward 

stepBackward 


Cell 4,1 or 5,1 if step buttons are enabled 
Cell 3,1 or 4,1 if step buttons are enabled 
Cell 5,1 or 6,1 if step buttons are enabled 
Cell 1,1 or 2,1 if step buttons are enabled 
Cell 2,1 or 3,1 if step buttons are enabled 
Cell 7,1 if step buttons are enabled 
Cell 1,1 if step buttons are enabled 


By knowing where the buttons are, you can easily extend this class by using 
addToCell (p. 1053) to add a vacant cell and to add a command handler to your 
object of this class to process the new buttons. 

Note: The identifiers for the animated buttons are the same as the identifiers for the 
bitmaps, which are defined in icconst.h. They are IC_FF, IC_REWIND, 
IC_PAUSE, IC_STOP, IC_STEPF, IC_STEPB, and IC_PLAY1. 


Public Functions 
Buttons 

Use these members to access the buttons on the player panel. 

fastForwardButton 

Returns a pointer to the fast forward animated button. 

Supported On: 

PM 

- Returns a pointer to the pause animated button. 


IAnimatedButton* 
fastForwardButton() const; 
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IAnimatedButton* 
pauseButton() const; 

—Returns a pointer to the play animated button. 


IAnimatedButton* 
playButton() const; 


rewind Button 

Returns a pointer to the rewind animated button. 


IAnimatedButton* 
rewindButton() const; 


stepBackwardButton 

Returns a pointer to the step backward animated button. 

IAnimatedButton* 
stepBackwardButton() const; 

stepForwardButton 

Returns a pointer to the step forward animated button. 

IAnimatedButton* 
stepForwardButton() const; 

-Returns a pointer to the stop animated button. 

IAnimatedButton* 
stopButton() const; 


Constructors 

You can construct and destruct objects of this class. 


IMMPlayerPanel 

You can construct objects of this class using the following parameters; 
identifier Window identifier of the player panel you construct. 

It is recommended that you; 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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• Give unique identifiers to all windows in the same frame window. In 
the same window means that the frame window is the first frame in 
their parent window chain. 

• Give the client window a window identifier of 
IC_FRAME_CLIENT_ID. 

parent The parent window of the player panel you construct. You must specify 
a parent window. This constructor throws an IlnvalidParameter exception 
if you pass an IWindow* of 0. The parent window is primarily used for 
visible relationships. 

owner The owner window of the player panel you construct. 

deviceType The type of device the player panel is going to control. The main use of 
this is to determine the type of buttons to be displayed on the player 
panel. Optional. 

initial The initial position and size of the player panel you construct. The 

initial position is the lower-left corner of the player panel relative to the 
lower-left corner of the parent window. Optional. 

style Use the styles provided by IMultiCellCanvas Style (p. 1063) to specify 

the control's styles. Optional. 


IMMP1 ayerPanel ( unsigned long identifier. Supported On: 

IWindow* parent, PM 

IWindow* owner, 

unsigned long deviceType = IMMDevice::other, 
const IRectangle& initial = IRectangle ( ), 
const IMultiCellCanvas::Style& style = 

IMultiCel1 Canvas::defaul tStyl e ( )); 

IPM The window identifier is limited to the range 0 through 65535. 

The owner window is primarily used for routing notification events and unprocessed 
messages. The operating system also uses the owner window chain to inherit colors. 

"IMMPlayerPanel 


virtual 

"IMMP1ayerPanel (); 


Supported On: 

PM 


Device 

Use these members to query and set the device that the player panel is going to control and to 
query the type of device that is being controlled. 
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_ Returns the type of device this player panel was created for. See the valid device 
types in IMMDevice (p. 873). 

unsigned long Supported On: 

deviceType(); PM 


playableDevice 

Returns a pointer to the IMMPlayableDevice (p. 972) the player is controlling. This 
allows the application to determine which device is set into the player panel. 

IMMP1 ayabl eDevi ce* Supported On: 

playableDevice() const; PM 

setPlayableDevice 

Sets a pointer to the IMMPlayableDevice (p. 972) that the player panel will control. 
This allows the player panel to control almost any device that the user wants. For 
example, you might want to control a digital video device. So, you would create an 
IMMDigitalVideo (p. 912) device and pass it on this call. When the user presses the 
player panel buttons, such as play or pause, these functions would act upon that 
IMMDigitalVideo device. 

IMMP1 ayerPanel & Supported On: 

setPl ayabl eDevi ce( IMMPlayableDevice* device); PM 


Inherited Public Functions 


IMultiCellCanvas 

addToCell 

enableDragLines 

rowHeight 

column Width 

enableGridLines 

setColumnWidth 

convertToGUIStyle 

hasDragLines 

setDefaultCell 

defaultCell 

hasGridLines 

setDefaultStyle 

defaultStyle 

isColumnExpandable 

setLay outDi storted 

disableDragLines 

isRowExpandable 

setRowHeight 

disableGridLines 

removeFromCell 

windowInCell 


ICanvas 

backgroundColor 

defaultStyle 

origDefaultB uttonHandle 

convertToGUIStyle 

isTabStop 

setDefaultStyle 
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ICanvas 

defaultPushButton 

matchForMnemonic 

setLayoutDistorted 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Functions 


IMultiCellCanvas 

layout 




ICanvas 

areChildrenReversed 

layout 

registerCallbacks 

calcMinimumSize 

layoutSize 

setLay outSize 

fixupChildren 

passEventT oO wner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


988 Open Class Library Reference 












IMMPlayerPanel 


Inherited Public Data 


IMultiCellCanvas 

classDefaultStyle 

dragLines 

gridLines 


ICanvas 

classDefaultStyle 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 
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IMMPlayerPanelHandler 


IBase 

IVBase 

IHandler 

ICommandHandler 

IMMPlayerPanelHandler 


_.None. 

_Jmmplyhtl.hpp 
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The IMMPlayerPanelHandler class processes the different command events for the 
player panel. You can override this class to provide more functionality or more 
precise control of the device. For example, you might call playFast instead of 
seekToEnd when the user presses the fast forward button for digital video. To do 
this, just subclass this class and implement your own processing for fast forward. 

The return value from the virtual functions specifies whether the command event is 
passed on for additional processing, as follows: 

true The command event requires no additional processing. Do not pass it to 
another handler. 

false The command event requires additional processing. Pass the command 
event on, as follows: 

• If there is another handler for the window, pass the command event on 
to the next handler. 

• If this is the last handler for the window, call 
IWindow::defaultProcedure (Vol. II) to process the command event. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IMMPlayerPanelHandler 

The User Interface Class Library provides only the default constructor for you to 
create a player panel handler object. 

IMMPlayerPanelHandlerQ; Supported On: 

PM 


"IMMPlayerPanelHandler 

virtual 

'IMMP1 ayerPanelHandler(); 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process. If it is, this function calls the virtual function used to process the event. 
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Calls the virtual functions to process a command event for a player panel. 


virtual Boolean 

command( ICommandEvent& event); 


Supported On: 

PM 


Event Processing 

Event processing members are invoked in response to the user pressing a button on the player 
panel, or they are invoked by the user of this class. These can be overridden to provide more 
functionality or more precise control of the device. All of these methods can be thought of as 
button presses, even though they might have been invoked directly. 

_Gets called when the user presses the fast forward button. The default action is to 
call seekToEnd (p. 978) on the device. It also unlatches the play and pause buttons 
and disables the stop and pause buttons. 

virtual Boolean Supported On: 

fastForward( const IMMP1 ayerPanel& panel); PM 


Exceptions 

IlnvalidRequest There must be a device set for the player panel. 


..Gets called when the user presses the pause button. The default action is to call 
pause (p. 975) on the device. If the device is already paused, it calls resume (p. 975) 
on the device and latches the play button. 

virtual Boolean Supported On: 

pause( const IMMP1 ayerPanel & panel); PM 


Exceptions 

IlnvalidRequest There must be a device set for the player panel. 


Gets called when the user presses the play button. The default action is to call play 
(p. 976) on the device. It also unlatches the pause button and enables the stop and 
pause buttons. 

virtual Boolean Supported On: 

play( const IMMP1 ayerPanel & panel); PM 


Exceptions 

IlnvalidRequest There must be a device set for the player panel. 
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..Gets called when the user presses the rewind button. The default action is to call 
seekToStart (p. 978) on the device. It also unlatches the play and pause buttons and 
disables the stop and pause buttons. 

virtual Boolean Supported On: 

rewind( const IMMP1 ayerPanel& panel); PM 


Exceptions 

IlnvalidRequest There must be a device set for the player panel. 


stepBackward 

Gets called when the user presses the step backward button. This is only possible 
when step is meaningful to the device, such as for video. The default action is to call 
stepFrame (p. 979) on the device. It also unlatches the play button. 

virtual Boolean Supported On: 

stepBackward( const IMMP1 ayerPanel & panel); PM 


Exceptions 

IlnvalidRequest There must be a device set for the player panel. 


_Gets called when the user presses the step forward button. This is only possible 
when step is meaningful to the device, such as for video. The default action is to call 
stepFrame (p. 979) on the device. It also unlatches the play button. 

virtual Boolean Supported On: 

stepForward( const IMMP1 ayerPanel & panel); PM 


Exceptions 

IlnvalidRequest There must be a device set for the player panel. 


Gets called when the user presses the stop button. The default action is to call stop 
(p. 977) and seekToStart (p. 978) on the device. It also unlatches the play and pause 
buttons and disables the stop and pause buttons. 

virtual Boolean Supported On: 

stop( const IMMP1 ayerPanel & panel); PM 


Exceptions 

IlnvalidRequest There must be a device set for the player panel. 
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Inherited Protected Functions 


ICommandHandler 

command 

dispatchHandlerEvent 

systemCommand 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMPositionChangeEvent 


IBase 

IVBase 

IEvent 

IMMPositionChangeEvent 


_.None. 


_ immevt.hpp 
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The IMMPositionChangeEvent class is the class for position change events. They get 
generated when you start position tracking for a device and the position of the device 
changes. Use startPositionTracking (p. 974) to cause these events to be generated. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMPositionChangeEvent 

Although you can construct objects of this class, typically 

IMMDeviceHandler::dispatchHandlerEvent (p. 910) creates objects of this class from 
an object of the class IEvent (Vol. II) or another IMMPositionChangeEvent object. 

IMMPositionChangeEvent( const IEvent& event); Supported On: 

PM 


IMMPositionChangeEvent 


virtual 

"IMMPositionChangeEventO; 


Supported On: 

PM 
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Event Information 

Use these members to return the position, device and user parameter for the device that generated 
this event. 

Returns a pointer to the device whose position is changing. 

IMMDevice* 
device() const; 

.Returns the position at the time the event was generated. 

IMMTime Supported On: 

position() const; PM 


Supported On: 

PM 


userParameter 

Returns the user parameter that was set at the time of this event. See 
IMMDevice::setUserParameter (p. 895) for more information. 

Supported On: 

PM 


unsigned short 
userParameter() const; 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMRecordable 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMFileMedia 

IMMRecordable 


IMMConfigurableAudio 


_Jmmrecrd.hpp 


Member 

Page 

Constructor 

1006 

canRedo 

999 

canUndo 

999 

copy 

999 

cueForRecording 

1000 

cut 

1000 

deleteSelection 

1001 


Member 

Page 

paste 

1001 

record 

1002 

redo 

1003 

save 

1003 

saveAs 

1004 

undo 

1004 

“IMMRecordable 

998 


The IMMRecordable class is a base class and provides all of the common behavior 
for all recordable media devices. There are functions for cutting, copying, and 
pasting from a clipboard. Also, it includes delete, undo, and save functions. 


Public Functions 
Constructors 

Derived classes can use these members to create objects of this class. 


"IMMRecordable 


virtual 

"TMMRecordableO ; 


Supported On: 

PM 
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Editing 

Use these members to edit and record data by the device. 

-Returns true if the device has any actions to be redone. 

Boolean Supported On: 

canRedo() const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Returns true if the device has any actions that can be undone. 


Boolean 

canl)ndo() const; 

Supported On: 

PM 

Exceptions 


IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Copies data from the passed in start position to the passed in end position into the 
clipboard. If from is omitted, it uses the current position; if to is omitted, it uses the 
end of the data. The clipboard is cleared before the copy occurs. 

virtual IMMRecordable& 
copy( const IMMTime& from = IMMTime ( ), 
const IMMTime& to = IMMTime ( ), 

CallType call = wait) const; 

Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the data. 


cueForRecording 

Cues the device for recording. This function causes any up front work that can occur 
to occur, thereby making the start of recording quick. This function does not have to 
be issued before recording; however, depending on the device, it might reduce the 
delay associated with the record (p. 1002) function. For example, a sound card might 
have to clear some internal buffers before it can start recording from a microphone. 

So this function would clear out those internal buffers for the sound card. 


virtual IMMRecordable& 
cueForRecording( CallType call = nowait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Cuts the data from the passed in start position to the passed in end position into the 
clipboard. If data is already in the clipboard, it is overwritten. If from is omitted, it 
will use the current position; if to is omitted, it uses the end of the data. 


virtual IMMRecordable& Supported On: 

cut( const IMMTime& from = IMMTime ( ), PM 

const IMMTime& to = IMMTime ( ), 

CallType cal 1 = wait); 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the data. 


deleteSelection 

Deletes data from the passed in start position to the passed in end position. If from is 
omitted, it uses the current position; if to is omitted, it uses the end of the data. 


virtual IMMRecordable& Supported On: 

deleteSelection( const IMMTime& from = IMMTime ( ), PM 

const IMMTime& to = IMMTime ( ), 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the data. 


Replaces the data with data from the clipboard, from the passed in start position to 
the passed in end position. If neither from nor to is specified, it inserts the data at the 
current position. If from is omitted, it uses the start of the buffer; if to is omitted, it 
uses the end of the audio data in the buffer. If convert is true, it causes the audio 
data in the clipboard to be converted to the current audio format before being pasted; 
otherwise, no conversion occurs. If you are pasting audio data, and audio format for 
data in the clipboard is incompatible with this device's audio format, then convert 
should be set to true; otherwise, an exception occurs. 
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virtual IMMRecordable& Supported On: 

paste( const IMMTime& from = IMMTime ( ), PM 

const IMMTime& to = IMMTime ( ), 

Boolean convert = true. 

Cal 1 Type cal 1 = wait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid from position; possibly the from position is greater than the end 
position or the from position is greater than the to position. 

IAccessError 

Invalid to position; possibly if the to position is greater than the length of 
the data. 

IAccessError 

The disk or buffer is full. 

IAccessError 

There is insufficient memory to perform the operation requested. 

IAccessError 

The clipboard format is not valid. 

IAccessError 

The clipboard cannot be opened. 

IAccessError 

No recognizable information is in the clipboard. 

IAccessError 

Unable to convert audio format in the clipboard to the destination audio 
format. 


Starts recording at the begin location till it reaches the end location. If the end 
location is not specified, recording continues until a pause or stop occurs. If the 
begin location is not specified, recording starts at the current location. It is 
recommended that you temporarily acquire the device exclusively while you are 
recording; otherwise, the recording can become inactive if another device requests 
access to the device. 


virtual IMMRecordable& 
record( Boolean insert = true, 

const IMMTime& begin = IMMTime 
const IMMTime& end = IMMTime ( 
Boolean resumelfPaused = true, 
Call Type call = nowait); 


Supported On: 

PM 

( ). 

), 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Invalid begin position; possibly the begin position is greater than the length 
of the data or the begin position is greater than the end position. 

IAccessError 

Invalid end position; possibly if the end position is greater than the length 
of the data. 

IAccessError 

The disk or buffer is full. 


Redoes the record, cut, paste, or delete operation most recently undone by undo. 

The position is at the beginning of the file after a redo. You can redo up to the last 
save, which causes any previous actions to be cleared and cannot be redone. Not all 
devices support his function. 

virtual IMMRecordable& Supported On: 

redo( Call Type call = wait); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Cannot redo. Redo is not possible in the current state; possibly there are 
no actions to be redone (that is, the file was just saved). 


..Saves the current file. 


virtual IMMRecordabl e& 

save( Call Type call = nowait); 

Supported On: 

PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 
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Exceptions 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file is not found; possibly the current data does not have a name. Use 
save As with the file name. 

IAccessError 

Save to a read-only file; possibly the currently loaded file was loaded as 
read-only. 

IAccessError 

The disk or buffer is full. 

IAccessError 

There is insufficient memory to perform the save operation. 


. Saves the current file as a different file. Any subsequent calls to the save (p. 1003) 
function will overwrite this file. 


virtual IMMRecordable& Supported On: 

saveAs( const IString& filename, PM 

Call Type call = nowait); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The file is not found; possibly the file name string does not contain a valid 
file name. 

IAccessError 

Save to a read-only file; possibly if the currently loaded file was loaded as 
read-only. 

IAccessError 

The disk or buffer is full. 

IAccessError 

There is insufficient memory to perform the save operation. 


.Undoes the operation most recently performed by cut, record, paste, or delete. After 
an undo, the position is at the beginning of the media. You can undo up to the last 
save, which causes any previous actions to be cleared and cannot be undone. Not all 
devices support his function. 

virtual IMMRecordable& 
undo( CallType call = wait); 


Exceptions 

IAccessError The device identifier is not valid; possibly the device is closed. 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

Cannot undo. Undo is not possible in the current state; possibly there are 
no actions to be undone (that is, the file is in the state where the last 
change was made). 


Inherited Public Functions 


IMMFileMedia 

filename 

isReadOnly 

load 


IMMPlayableDevice 

addCuePoint 

position 

seekToStart 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports V olume Adj ustment 
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IMMDevice 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

Derived classes can use these members to create objects of this class. 

IMMReeordable 

[J IMMRecordable( const IString& deviceName, Supported On: 

Boolean openNow, PM 

unsigned long instance. 

Boolean openShareable); 

A derived class can construct an IMMReeordable from the following: 
deviceName 

You must specify what device you wish to construct. 

openNow If true, it causes the device to automatically open the device before 
returning from the constructor; otherwise, you have to call one of the 
open (p. 887) functions to open the device yourself. 
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instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 

§ IMMRecordable( unsigned long deviceldentifier. Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMReeordable from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Inherited Protected Functions 


IMMFileMedia 

setReadOnlyFlag 




IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 
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Inherited Public Data 


IMMDevice 

allDevices 

cuePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digitalVideo 

positionChangeld 

audioTape 

headphone 

sequencer 

cdxa 

microphone 

speaker 

commandNotifyld 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



1008 Open Class Library Reference 







IMMRemovableMedia 



IM M Rem ovab I e Med i a 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMRemovableMedia 


IMMAudioCD 

IMMCDXA 


Mmmremed.hpp 


Member 

Page 

Member 

Page 

Constructor 

1013 

mediaLoadedld 

1014 

closeDoor 

1010 

openDoor 

1011 

isMediaPresent 

1010 

unlockDoor 

1011 

lockDoor 

1010 

'IMMRemovableMedia 

1010 


The IMMRemovableMedia provides all of the common behavior for all removable 
media devices. The main purpose of this class is to provide functions for devices that 
have physical media that is replaceable. Some examples of devices that might inherit 
from this are videoDiscs, CD players, cassette players, and VCRS. There are 
functions for loading or ejecting media, determining if media is present, and locking 
and unlocking a door on the device. Derived classes can use the virtual functions 
mediaLoaded and mediaUnloaded for determining if someone is changing the media. 


Public Functions 
Constructors 

Derived classes can use these members to create objects of this class. 
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IMMRemovableMedia 


virtual 

"TMMRemovableMediaO ; 


Supported On: 

PM 


Door and Presence 

Use these members to open, close, lock, and unlock the door on the removable media device. 
-Retracts the tray and closes the door, if possible. 

virtual IMMRemovableMedia& Supported On: 

closeDoor( Call Type call = wait); PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


isMediaPresent 

Returns true if media is inserted in the device; otherwise, it returns false. 


Bool ean Supported On: 

isMediaPresent( CallType call = wait) const; PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


.Locks the media cover on the device, if any. This disables manual ejection of the 

media from the device. 


virtual IMMRemovableMedia& 
lockDoor( Boolean lock = true. 
Cal 1 Type cal 1 = wait); 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 


IlnvalidRequest 

The device must be in the open state before calling this function. 

.Opens the door and ejects the tray, if possible. 


virtual IMMRemovabl eMedi a& 
openDoor( Boolean open = true. 

Cal 1 Type cal 1 = wai t); 

Supported On: 

PM 

Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; 
device of this same type was acquired for exclusive use in 
process. 

possibly another 
this or another 

IAccessError 

An internal driver error occurred. 


IlnvalidRequest 

The device must be in the open state before calling this function. 


—Unlocks the media cover on the device, if any. This enables manual ejection of the 
media from the device. 


virtual IMMRemovableMedia& 
unlockDoor( CallType call = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


Inherited Public Functions 


IMMPlayableDevice 

addCuePoint 

position 

seekToStart 
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IMMPlayableDevice 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports Volume Adjustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Constructors 

Derived classes can use these members to create objects of this class. 

IMMRemovableMedia 

Q IMMRemovableMedia( const IString& deviceName, Supported On: 

Boolean openNow, PM 

unsigned long instance. 

Boolean openShareable); 

A derived class can construct an IMMRemovableMedia from the following: 
deviceName 

You must specify what device you wish to construct. 

openNow If true, it causes the device to automatically open the device before 
returning from the constructor; otherwise, you have to call one of the 
open (p. 887) functions to open the device yourself. 

instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 

g IMMRemovableMedia( unsigned long deviceldentifier. Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMRemovableMedia from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Inherited Protected Functions 


IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 
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IMMDevice 

itemCapability 

openStatus 

setUserParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Public Data 

Notification Event Descriptions 

This INotificationld string is used for notifications that IMMRemovableMedia provides to its 
observers. 

mediaLoadedld 

Notification identifier provided to observers when the current media-loaded state 
changes. IMMRemovableMedia provides a Boolean value in the eventData (Vol. I) 
field of the INotificationEvent (Vol. I). This value will be true if the media is loaded 
and false, if the media is unloaded. 

static const INotificationld Supported On: 

mediaLoadedld; PM 


Inherited Public Data 


IMMDevice 

allDevices 

euePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digitalVideo 

positionChangeld 

audioTape 

headphone 

sequencer 

cdxa 

microphone 

speaker 
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IMMDevice 

commandN otify Id 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


I Base 

recoverable 

unrecoverable 
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IMMRemovableMediaHandler 


IBase 

IVBase 

IHandler 

IMMDeviceHandler 

IMMRemovableMediaHandler 


_.None. 


Mmmremhd.hpp 


Member 

Page 

Member 

Page 

Constructor 

1016 

mediaUnloaded 

1017 

handleEventsFor 

1017 

passDevice 

1017 

mediaLoaded 

1017 

'IMMRemovableMediaHandler 

1017 


The IMMRemovableMediaHandler class is the base handler class for removable 
devices. This class provides the ability for derived classes to implement their own 
processing when media is loaded or unloaded from a device. For example, if the user 
ejects the CD from a CD player, then you might want to gray out the controls of the 
CD player until the user inserts a new CD. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMRemovableMediaHandler 

Creates IMMRemovableMediaHandler objects. 

IMMRemovableMediaHandler(); Supported On: 

PM 
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IMMRemovableMediaHandler 


virtual 

'IMMRemovableMediaHandler(); 


Supported On: 

PM 


Device Attachment 

Use these members to attach the handler object to or from a given device. 


handleEventsFor 

Attaches the handler to the specified IMMDevice (p. 873) object. This is overridden 
to force attachment of this handler to only one device. 


virtual IMMRemovableMediaHandler& 
handleEventsFor( IMMDevice* device); 


Supported On: 

PM 


Event Processing 

Derived classes must supply these functions to process a pass device event. 

.. Processes pass device events. It is implemented by derived classes. 

virtual Boolean Supported On: 

passDevice( const IMMPassDeviceEvent& event); PM 


Media Loading 

Use these members to provide processing when media is either loaded or unloaded from the 
device. They are implemented by derived classes. 

mediaLoaded 

Called whenever media is loaded into the device. 


virtual IMMRemovableMediaHandler& 
mediaLoaded(); 


Supported On: 

PM 


mediaUnloaded 

Called whenever media is unloaded from the device. 


virtual IMMRemovableMediaHandler& 
mediaUnloaded(); 


Supported On: 

PM 
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Inherited Public Functions 


IMMDeviceHandler 

cuePoint 

handleEventsFor 

positionChange 

deviceEvent 

passDevice 

stopHandlingEventsFor 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMDeviceHandler 

dispatchHandlerEvent 




IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMSequencer 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMFileMedia 

IMMSequencer 


_.None. 

—immsequ.hpp 


Member Page 

Constructor 1019 

isOpenStringValid 1022 

'IMMSequencer 1020 


The IMMSequencer class is the base class for MIDI (Musical Instrument Digital 
Interface) playback. MIDI is a standard specification for playing back music from a 
series of commands, rather than from actual audio data. The commands represent 
musical events, such as turning a note on and off, as well as timing mechanisms for 
specifying the duration of the note's sound. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMSequencer 


IMMSequencer( Boolean openNow = true. Supported On: 

unsigned long instance = 0, PM 

Boolean openShareable = true); 

You can construct an IMMSequencer from the following: 
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openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 

instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 


IMMSequencer 

virtual 

'IMMSequencerO ; 


Supported On: 

PM 


Inherited Public Functions 


IMMFileMedia 

filename 

isReadOnly 

load 


IMMPlayableDevice 

addCuePoint 

position 

seekToStart 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 
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IMMDevice 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports V olume Adj ustment 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. 

Supported On: 

PM 

Optional. 


IMMSequencer( unsigned long deviceldentifier, 

const IString& newAlias = IString ( )); 

A derived class can construct an IMMSequencer from the following: 

deviceldentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. 
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Implementation 

These members check if the passed in string is in the correct format to open the current device. 


isOpenStringValid 

Returns true if the passed in open string is valid for this device. 


virtual Boolean 

isOpenStringValid( const IString& deviceName) const; 


Supported On: 

PM 


Inherited Protected Functions 


IMMFileMedia 

setReadOnlyFlag 




IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Inherited Public Data 


IMMDevice 

allDevices 

euePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digitalVideo 

positionChangeld 

audioTape 

headphone 

sequencer 
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IMMDevice 

cdxa 

microphone 

speaker 

commandN otify Id 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMMSpeed 


IBase 

IVBase 

IMMSpeed 


_.None. 

Mmmspeed.hpp 


Member 

Page 

Member 

Page 

Constructor 

1024 

speed 

1025 

format 

1025 

'IMMSpeed 

1025 


The IMMSpeed class provides the speed functions in frames-per-second and as a 
percentage. The percentage value refers to a percent of the maximum speed for the 
device. A case for when you might use a percentage follows. You currently are 
playing video at the device's fastest rate, 100 percent. You want to cut down that 
playback to only 60 percent of what it currently is playing. To do this, create an 
IMMSpeed(60) and pass it to the set speed function. If you want the video to 
playback at specific frames-per-second value, use the frames-per-second format. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IMMSpeed 

| IMMSpeed( Format format, 

unsigned long speed); 

2 IMMSpeed( unsigned long percent = 100); 


Supported On: 

PM 


Supported On: 

PM 
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"IMMSpeed 


virtual 

"IMMSpeedO ; 


Supported On: 

PM 


Format 

Use these members to specify the speed as a percentage or in frames-per-second. These 
members return the current speed format and value. 

Returns the current speed format. This is either in frames-per-second or percentage. 


Format Supported On: 

format() const; PM 

.Returns the speed value as either a percentage or in frames-per-second. 


virtual unsigned long 
speed() const; 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Format { 

percentage = 3, 
framesPerSecond 
}; 


Enumeration for specifying the way the speed is determined. 
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IMMTime 


IBase 

IVBase 

IMMTime 


IMMHourMinSecFrameTime IMMMinSecFrameTime 

IMMFIourMinSecTime IMMTrackMinSecFrameTime 

IMMMillisecondTime 


—immtime.hpp 


Member 

Page 

Constructor 

1027 

asMMTime 

1028 

asString 

1028 

defaultTime 

1032 

hours 

1027 

hundredths 

1027 

is Valid 

1028 

minutes 

1027 

operator != 

1029 

operator + 

1029 

operator += 

1029 

operator - 

1029 

operator -= 

1029 

operator < 

1030 


Member 

Page 

operator <= 

1030 

operator = 

1028 

operator == 

1030 

operator > 

1030 

operator >= 

1030 

operator unsigned long 

1028 

ordinal 

1031 

seconds 

1027 

setMMTime 

1032 

setTimeToOrdinal 

1031 

set Valid 

1032 

thousandths 

1027 

'IMMTime 

1028 


The IMMTime base device time class provides behavior common to all device times. 
IMMTime is the standard time and media position format supported by all of the 
multimedia devices. This time unit is 1/3000 second, or 333 microseconds. Most 
time values can be represented as unsigned long values. This class also provides 
function for converting an IMMTime value to an unsigned long value. All time 
values are based on 4 bytes. Because each time class is in different units, the 
maximum time value that each can contain is different. 
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Public Functions 
Attributes 

Use these members to parse the time into normal time values, for example, hours, minutes, and 
seconds. 


Returns the hours component of the time. 


virtual unsigned long Supported On: 

hours() const; PM 

—Returns the millisecond component of the time rounded to the nearest hundredth. 


virtual unsigned long Supported On: 

hundredths() const; PM 

Returns the minutes component of the time. This is in the range of 0 to 59. 


virtual unsigned long Supported On: 

minutes() const; PM 

Returns the seconds component of the time. This is in the range of 0 to 59. 


virtual unsigned long Supported On: 

seconds() const; PM 

—Returns the millisecond component of the time rounded to the nearest thousandth. 


virtual unsigned long 
thousandths() const; 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. 


IMMTime 


| IMMTime( unsigned long time = defaultTime); 


Supported On: 

PM 


You can construct an IMMTime from: 

time A time value where each unit is equal to 1/3000 second. 
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Supported On: 

PM 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time was invalid. 


IMMTime 


2 IMMTime( const IMMTime& time); 

_ Sets the time to be equal to the passed in time. 
IMMTime& 

operator =( const IMMTime& time); 


virtual 
"IMMTimeQ; 


Supported On: 

PM 


Conversions 

Use these members to cast the time to an unsigned long or an unsigned long that is in the 
IMMTime format. 

-.Returns this time value as an unsigned long that can be used to create an IMMTime 
(p. 1026). By default, this returns this time value. Derived classes should override 
this function to provide a way to be converted to an IMMTime value. 

virtual unsigned long Supported On: 

asMMTime() const; PM 

_Returns the time as a unsigned long where each time unit is equal to 1/3000 of a 

second. 

virtual Supported On: 

operator unsigned long() const; PM 


Diagnostics 

Use these members to return the time as a string and allow you to determine if the time is valid. 
..Returns the time value as a string formatted as HH:MM:SS.MMM. 


virtual IString Supported On: 

asString() const; PM 

Returns true if the time value is valid. 
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virtual Boolean 
isValid() const; 


Supported On: 

PM 


Operators 

Use these operators to perform different mathematical operations on this time object. 
_ Returns true if this time is not equal to the passed in time. 


Boolean 

operator !=( const IMMTime& time) const; 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Returns the sum of this time and the passed in time. 


IMMT i me Supported On: 

operator +( const IMMTime& time) const; PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Adds the passed in time from this time object 


IMMTime& Supported On: 

operator +=( const IMMTime& time); PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


_ Returns the result of this time minus the passed in time. 


I MMT i me Supported On: 

operator -( const IMMTime& time) const; PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


..Subtracts the passed in time from this time object. 
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IMMTime& Supported On: 

operator -=( const IMMTime& time); PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Returns true if this time is less than the passed in time. 


Boolean 

operator <( const IMMTime& time) const; 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Returns true if this time is less than or equal to the passed in time. 


Boolean 

operator <=( const IMMTime& time) const; 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Returns true if this time is equal to the passed in time. 


Boolean 

operator ==( const IMMTime& time) const; 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Returns true if this time is greater than the passed in time. 


Boolean 

operator >( const IMMTime& time) const; 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


. Returns true if this time is greater than or equal to the passed in time. 
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Boolean 

operator >=( const IMMTime& time) const; 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Ordinal 

Use these member to indicate generic positions. A time object returns an ordinal number, which 
represents the time at some particular granularity. This is useful for something that allows 
seeking and displays position, such as a slider. Because sliders generally do not process time 
values, use an ordinal number to establish the range of slider values. Ordinal numbers can be 
mathematically manipulated and converted back to time values, if necessary. 

Note: Some time values are difficult to represent as an ordinal value, such as 

IMMTrackMinSecFrameTime. Such a time object produces ordinal numbers that are 
dependent on unknown information, such as the table of contents of a CD. Some time 
classes might not be able to correctly implement setTimeToOrdinal (p. 1031). 

Returns an ordinal number in milliseconds. By default, this is the time converted to 
milliseconds. Not all derived classes can return milliseconds. 

virtual unsigned long Supported On: 

ordinal () const; PM 

setTimeToOrdinal 

Sets the time object to the value represented by the ordinal number in milliseconds. 

virtual IMMTime& Supported On: 

setTimeToOrdinal ( unsigned long ordinal); PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Implementation 

These members set the validity of the time and change the time to a new value. 

- Sets the current set time to the new value. The time unit for this value is 1/3000 
second. 

IMMTime& Supported On: 

setMMTime( unsigned long newTime); PM 

.Sets the validity of the current time value. With setValid, derived classes can 

change the validity of the time value. Validity means that this time object represents 
a valid time. 

IMMT i me& Supported On: 

setValid( Boolean Valid = true); PM 


Public Data 
Constructors 

You can construct and destruct objects of this class. 
_Used to denote a default time. 


static const unsigned long 
defaultTime; 

Supported On: 

PM 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 



Format { 



milliseconds = 1, 

mmTime, 

minSecFrame = 5, 

trackMinSecFrame, 

frames = 8, 

hourMinSec, 

bytes = 11, 

samples. 

hourMinSecFrame, 

mm24FramesPerSecond, 

mm30FramesPerSecondDrop 

mm25FramesPerSecond, 

mm30FramesPerSecond 


1 ; 
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Enumeration which denotes the different allowable time formats. Valid values are: 

milliseconds 

Represents the 1/1000 of a second time format. 

mmTime 

Represents the 1/3000 of a second time format. 

minSecFrame 

Represents the time format based on the 75-frames-per-second CD digital audio 
standard (another name for this is Red Book time format). 

trackMinSecF rante 

Represents the tracks-minutes-seconds-frames time format based on the 
75-frames-per-second CD digital audio standard. This format is used primarily 
by CD audio devices. 

frames 

Represents the digital video frames time, where a number corresponds to a 
frame number. 

hourMinSec 

Represents the hours-minutes-seconds time format commonly used by 
videoDisc and digital video players. 

bytes 

Represents the wave audio bytes time, where a number corresponds to a byte 
number. 

samples 

Represents the wave audio samples time, where a number corresponds to a 
sample number. 

hourMinSecF rame 

Represents the hours-minutes-seconds-frames time commonly used by 
videoDisc and digital video players. 

nmi24F ramesPerSecond 

Represents the frame-numbering system developed by the Society of Motion 
Picture and Television Engineers that assigns a number to each frame of video 
based on 24 frames-per-second. 

mm25FramesPerSecond 

Represents the frame-numbering system developed by the Society of Motion 
Picture and Television Engineers that assigns a number to each frame of video 
based on 25 frames-per-second. 
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mm30FramesPerSecond 

Represents the frame-numbering system developed by the Society of Motion 
Picture and Television Engineers that assigns a number to each frame of video 
based on 30 frames-per-second. 

30F ramesPerSecondDrop 

Represents the frame-numbering system developed by the Society of Motion 
Picture and Television Engineers that assigns a number to each frame of video 
based on 30 frames-per-second. 
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IMMTrackMinSecFrameTime 


IBase 

IVBase 

IMMTime 

IMMTrackMinSecFrameTime 


_.None. 


_ immttime.hpp 
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1037 
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1037 

seconds 

1035 
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1036 

'IMMTrackMinSecFrameTime 

1037 


The IMMTrackMinSecFrameTime data type class represents the 
tracks-minutes-seconds-frames (TTMMSSFF) time format. This format is used 
primarily by compact disc audio devices. 


Public Functions 
Attributes 

Use these members to parse the data into tracks, seconds, minutes, and frames. 
Returns the frames component of the time. 


virtual unsigned long Supported On: 

frames() const; PM 

Returns the minutes component of the time. This is in the range of 0 to 59. 

virtual unsigned long Supported On: 

minutesO const; PM 

Returns the seconds component of the time. This is in the range of 0 to 59. 
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virtual unsigned long 
seconds() const; 

Returns the track component of the time. 


virtual unsigned long 
track() const; 


Constructors 

You can construct, copy and desttuct objects of this class. 


IMMTrackMinSecFrameTime 

P IMMTrackMinSecFrameTime( IMMAudioCDContents& contents, 

unsigned long track, 
unsigned long minutes, 
unsigned long seconds, 
unsigned long frames); 

You can construct an IMMHourMinSecFrameTime from: 

contents A table of contents for the compact disc that you want to 
for. 

track A track number. 

minutes The number of minutes. 

seconds The number of seconds. 

frames The number of frames. 


2 IMMTrackMinSecFrameTime( const IMMTrackMinSecFrameTime& time); 

0 IMMTrackMinSecFrameTime( IMMAudioCDContents& contents, 

unsigned 1ong value); 

You can construct an IMMTrackMinSecFrameTime from: 

contents A table of contents for the compact disc that you want to 
for. 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


create a time 


Supported On: 

PM 


Supported On: 

PM 


create a time 
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value A time value where: 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the track 

_ Sets the time to be equal to the passed in time. 

IMMTrackMinSecFrameTime& Supported On: 

operator =( const IMMTrackMinSecFrameTime& time); PM 


Exceptions 

IlnvalidRequest The passed in time is invalid. 


IMMT rackMinSecFrameTime 


virtual 

"IMMTrackMinSecFrameTimeO; 


Supported On: 

PM 


Conversion 

Use these members to cast the time to an unsigned long. 

_Returns the time as a unsigned long in the following format (FFSSMMTT): 

1. 1st byte is the frames 

2. 2nd byte is the seconds 

3. 3rd byte is the minutes 

4. 4th byte is the tracks 

This value is based on the current table of contents. 

virtual Supported On: 

operator unsigned long() const; PM 


Diagnostics 

Use these members to return the time as a string. 

_Returns the time value as a string formatted as TT MM:SS.FF. 


virtual IString 
asString() const; 


Supported On: 

PM 
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Operators 

Use these operators to perform mathematical operations on time objects. 

- Returns the sum of the current set time and the passed in time. 


IMMTrackMinSecFrameTime 
operator +( const IMMTime& time); 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Adds the time to the current set time. 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


IMMTrackMinSecFrameTime& 
operator +=( const IMMTime& time); 


_ Returns the result of the current set time minus the passed in time. 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


IMMTrackMinSecFrameTime 
operator -( const IMMTime& time); 


Subtracts the time from the current set time. 


IMMTrackMinSecFrameTime& 
operator -=( const IMMTime& time); 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The passed in time is invalid or this time object is invalid. 


Inherited Public Functions 


IMMTime 

asMMTime 

operator + 

operator == 
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IMMTime 

asString 

operator += 

operator > 

hours 

operator - 

operator >= 

hundredths 

operator -= 

operator unsigned long 

is Valid 

operator < 

ordinal 

minutes 

operator <= 

seconds 

operator != 

operator = 

setTimeToOrdinal 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IMMTime 

setMMTime 

set Valid 



Inherited Public Data 


IMMTime 

defaultTime 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



© IBM Corp. 1992, 1995 


IMMTrackMinSecFrameTime 1039 






EMM'W ave Audio 



IMMWaveAudio 


IBase 

IVBase 

INotifier 

IStandardNotifier 

IMMDevice 

IMMPlayableDevice 

IMMFileMedia 

IMMRecordable 

IMMConfigurableAudio 

IMMWaveAudio 


_.None. 


_ immwave.hpp 
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The IMMWaveAudio class provides recording and playing of sound files. The sound 
files are stored in a waveform format. Not only can you use the inherited functions, 
such as play, pause, setFormat, you can also use this class for cutting, copying, and 
pasting to and from an audio buffer. 


Public Functions 
Buffers 

Use these members to edit the audio using buffers and setting attributes for the current audio. 


copyFromBuffer 

Copies all of the audio data from the audio buffer to the current location. 
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virtual IMMWaveAudio& 

copyFromBuffer( const IMMAudioBuffer& audioBuffer, 
Cal Hype cal 1 = wai t); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 


copyToBuffer 

Copies audio data into the audio buffer front the passed in begin position to the 
passed in end position. If from is omitted, it uses the current position; if to is 
omitted, it uses the end of the audio data. 

virtual IMMWaveAudio& Supported On: 

copyToBuffer( IMMAudioBuffer& audioBuffer, PM 

const IMMTime& from = IMMTime ( ), 
const IMMTime& to = IMMTime ( ), 

CallType call = wait) const; 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The buffer is too small to hold that data. 

IAccessError 

The passed in range is invalid; either the to or the from position does not 
point to a valid position or the difference between from and to is not 
greater than zero. 


cutCopyBufferSize 

Returns the size the audio buffer needs to be to contain the audio data from the 
passed in beginning position to the passed in ending position. If from is omitted, it 
uses the current position; if to is omitted, it uses the end of the audio data. 


virtual unsigned long 
cutCopyBufferSize( const 
const 


IMMTime& from = IMMTime ( ), 
IMMTime& to = IMMTime ( )) const; 


Supported On: 

PM 
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Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The buffer is too small to hold that data. 

IAccessError 

The passed in range is invalid; either the to or the from position does not 
point to a valid position or the difference between from and to is not 
greater than zero. 


-Cuts audio data into the audio buffer from the passed in start position to the passed 
in end position. If from is omitted, it uses the current position; if to is omitted, it 
uses the end of the audio data. 

virtual IMMWaveAudio& 
cutToBuffer( IMMAudioBuffer& audioBuffer, 

const IMMTime& from = IMMTime ( ), 
const IMMTime& to = IMMTime ( ), 

Cal Hype cal 1 = wai t); 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The buffer is too small to hold that data. 

IAccessError 

The passed in range is invalid; either the to or the from position does not 
point to a valid position or the difference between from and to is not 
greater than zero. 


Supported On: 

PM 


pasteFromBuffer 

Replaces the audio data with data from the audio buffer, from the passed in begin 
position to the passed in end position. If neither from nor to is specified, then it 
inserts the data at the current position. If from is omitted, it uses the start of the 
buffer; if to is omitted, it uses the end of the audio data in the buffer. 
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virtual IMMWaveAudio& 

pasteFromBuffer( const IMMAudioBuffer& audioBuffer, 
const IMMTime& from = IMMTime ( ), 
const IMMTime& to = IMMTime ( ), 
Cal 1 Type cal 1 = wait); 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The passed in range is invalid; either the to or the from position does not 
point to a valid position or the difference between from and to is not 
greater than zero. 


pasteToBuffer 

Pastes audio data into the passed in audio buffer. 


virtual IMMWaveAudio& 

pasteToBuffer( IMMAudioBuffer& audioBuffer, 
CallType call = wait) const; 


Supported On: 

PM 


Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The buffer is too small to hold that data. 


supportsWaveFormat 

Returns true, if the format is supported. This allows an application to determine 
whether a specific wave audio format is supported. 

virtual Boolean Supported On: 


supportsWaveFormat( unsigned 

long bitsPerSample. 

PM 

unsigned 

long samplesPerSecond, 


unsigned 

long channels. 



IMMAudioBuffer::Format format, 
CallType call = wait) const; 
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Exceptions 

IAccessError 

The device identifier is not valid; possibly the device is closed. 

IAccessError 

The device cannot acquire access to the hardware device; possibly another 
device of this same type was acquired for exclusive use in this or another 
process. 

IAccessError 

An internal driver error occurred. 

IlnvalidRequest 

The device must be in the open state before calling this function. 

IAccessError 

The device hardware does not support this format; possibly the 
combination of the passed in audio attributes is not supported by the 
system. 


Constructors 

You can construct and destruct objects of this class. 

IMMWaveAudio 

IMMWaveAudio( Boolean openNow = true. Supported On: 

unsigned long instance = 0, PM 

Boolean openShareable = true); 

You can construct an IMMWaveAudio from the following: 

openNow If true, it causes the device to automatically open the device before 

returning from the constructor; otherwise, you would have to call one of 
the open (p. 887) functions to open the device yourself. 

instance The user can provide their own instance number instead of one being 
generated for them. 

openShareable 

If true, it allows the hardware device to be shared by different programs; 
otherwise, the hardware cannot be shared. 


"IMMWaveAudio 

virtual 

'IMMWaveAudioO ; 


Supported On: 

PM 


Inherited Public Functions 


IMMConfigurableAudio 

bitsPerS ample 

format 

setBytesPerSecond 
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blockAlignment 

samplesPerSecond 

setChannels 

bytesPerSecond 

setBitsPerS ample 

setFormat 

channels 

setB lockAlignment 

setSamplesPerSecond 


IMMRecordable 

canRedo 

cut 

redo 

canUndo 

deleteSelection 

save 

copy 

paste 

saveAs 

cueForRecording 

record 

undo 


IMMFileMedia 

filename 

isReadOnly 

load 


IMMPlayableDevice 

addCuePoint 

position 

seekToStart 

cueForPlayback 

removeCuePoint 

startPositionTracking 

length 

resume 

stepFrame 

pause 

seek 

stop 

play 

seekToEnd 

stopPositionTracking 


IMMDevice 

acquire 

isCloseOnDestroy 

speedFormat 

aliasName 

isConnectionSupported 

supportsAudio 

close 

isConnectorEnabled 

supportsCommand 

connectedDeviceld 

isOpen 

supportsDigitalTransfer 

deletePendingEvents 

mode 

supportsDisableEject 

description 

open 

supportsEject 

deviceld 

openOnThread 

supportsPlay 

deviceName 

prerollTime 

supportsRecord 

deviceType 

prerollType 

supportsRecordlnsertion 

disableAudio 

release 

supportsSave 

disableConnector 

requiresFiles 

supportsStreaming 

enableAudio 

setCloseOnDestroy 

supports Video 

enableConnector 

setSpeedFormat 

supports V olume Adj ustment 


© IBM Corp. 1992, 1995 


IMM W aveAudio 1045 









EMM'W aveAudio 


IMMDevice 

isAcquired 

setTimeFormat 

timeFormat 

isAudioEnabled 

set Volume 

volume 


IStandardNotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. 


IMMWaveAudio( unsigned long deviceldentitier. Supported On: 

const IString& newAlias = IString ( )); PM 

A derived class can construct an IMMWaveAudio from the following: 

deviceidentifier 

The value the system uses to identify the device. 
newAlias The name you can use to associate a string to the device. Optional. 


Implementation 

These members check if the passed in string is in the correct format to open the current device. 
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isOpenStringValid 

Returns true if the passed in open string is valid for this device. 


virtual Boolean 

isOpenStringValid( const IString& deviceName) const; 


Supported On: 

PM 


Inherited Protected Functions 


IMMConfigurableAudio 

translateAudioFlag 




IMMFileMedia 

setReadOnlyFlag 




IMMDevice 

deviceWindow 

open 

setOpenStatus 

isOpenString V alid 

openOnThread 

setPassDeviceRequested 

itemCapability 

openStatus 

setU serParameter 

itemStatus 

sendCommand 

userParameter 

lastError 

setLastError 

wasPassDeviceRequested 


IStandardNotifier 

addObserver 

notifyObservers 

observerList 


INotifier 

addObserver 

notifyObservers 

observerList 


Inherited Public Data 


IMMDevice 

allDevices 

cuePointld 

other 

ampMixer 

dat 

overlay 

animation 

deviceEventld 

passDeviceld 

audioCD 

digital Video 

positionChangeld 

audiotape 

headphone 

sequencer 
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IMMDevice 

cdxa 

microphone 

speaker 

commandNotifyld 

monitor 

videoDisc 


IStandardNotifier 

deleteld 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBase 

IVBase 

INotifier 

IWindow 

IControl 

ICanvas 

IMultiCellCanvas 


IMMPlayerPanel 


_ imcelcv.hpp 


Member 

Page 

Member 

Page 

Constructor 

1055 

hasGridLines 

1057 

addToCell 

1053 

isColumnExpandable 

1058 

classDefaultStyle 

1063 

isRowExpandable 

1059 

columnWidth 

1058 

layout 

1062 

convertToGUIStyle 

1061 

removeFromCell 

1054 

defaultCell 

1058 

rowHeight 

1059 

defaultStyle 

1061 

setColumnWidth 

1059 

disableDragLines 

1056 

setDefaultCell 

1060 

disableGridLines 

1056 

setDefaultStyle 

1061 

dragLines 

1063 

setLayoutDistorted 

1057 

enableDragLines 

1057 

setRowHeight 

1060 

enableGridLines 

1057 

windowInCell 

1055 

gridlines 

1063 

'IMultiCellCanvas 

1056 

hasDragLines 

1057 




Objects of the IMultiCellCanvas class manage a collection of child windows in a way 
similar to that of data stored in a spread sheet. A multiple-cell canvas is a 
two-dimensional array of cells with an origin of (1,1) in the upper-left corner. 
Windows are added to a multiple-cell canvas by specifying a starting cell and, 
optionally, a number of contiguous columns, rows, or a combination thereof. 

This class bases the initial cell sizes on the minimum sizes returned by each child 
window of the canvas. You can override the minimum sizes provided by the User 
Interface Class Library by doing either of the following: 

• Calling setMinimumSize 

• Creating a derived class and implementing a calcMinimumSize function 
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The user cannot resize fixed rows or columns by changing the size of the 
multiple-cell canvas. 

Undesirable movement of the windows might result when a multiple-cell parent 
canvas updates its child windows. You can avoid this by calling IStaticText::setLimit 
so that the static text bases its minimum size on an expected number of characters 
rather than its actual text string. 


The following figure illustrates the positioning of three static text controls, three entry 
fields, and two push buttons: 


1 2 


1 

2 

3 

4 

5 

6 

7 

8 


10 

11 


* MCELCV.EXE 


n 


Please identify yourself below. 
Name 

Serial number 
Password 


OK 


Cancel 


D S 3 


Because there is no text in either row 1 or column 1, row 1 and column 1 take the 
default cell size. As you can see in the figure, the default cell size is relatively small 
and therefore preserves screen space. Also, using the default cell size for column 1 
and row 1 creates some padding, or margin, around the child windows that you place 
in the multiple-cell canvas. 

Positioning Static Text Controls Example 

The first static text control has a starting cell of (2, 2). The child window that 
contains the static text control exists in one row, row 2, and extends from column 2 
through column 7. It occupies six columns (2, 3, 4, 5, 6, and 7). The following 
addToCell call was used to produce it, where myClient is the client window multicell 
canvas: 

myClient.addToCell(&prompt, 2, 2, 6, 1); 


The name of the child window that contains the static text control is prompt. The 
two numbers that follow the name specify the starting column and row, (2, 2). The 
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last two numbers, (6, 1), specify that the control extends through six columns and 
occupies one row. 

The other static text controls, which contain the text strings "Name," "Serial number," 
and "Password," have starting cells of (3, 4), (3, 6), and (3, 8), respectively. The 
following addToCell calls were used to produce them: 

myClient.addToCel1(&namePrompt, 3, 4); 
myClient.addToCel1(&numberPrompt, 3, 6); 
myClient.addToCel1(&passwordPrompt, 3, 8); 


Notice that we did not specify the number of columns and rows for these text 
controls to occupy. This means the columns and rows take the default, which is one 
column and one row. The width of column 3 is based on the static text control that 
contains "Serial number." 

Positioning Entry Fields Example 

The first entry field has a starting cell of (5, 4) and extends through three columns 
(columns 5, 6, and 7) while occupying one row. The first static text control has 
already determined the width of these columns, so this entry field is stretched to the 
right edge of column 7. 

The second entry field has a starting cell of (5, 6) and occupies the default of one 
column and one row. This means that the width of column 5 is based on the width 
of the second entry field, because it only occupies one column. 

The third entry field has a starting cell of (5, 8), spanning two columns and one row. 
Here are the addToCell calls for the entry fields: 

myClient.addToCel1(&name, 5, 4, 3, 1); 

myClient.addToCel1(&number, 5, 6); 

myClient.addToCel1(&password, 5, 8, 2, 1); 


Using Expandable Rows and Columns Example 

In the figure, column 7 is much wider than you might expect. You might think that 
it should be the same size as all of the other columns except 3 and 5, which are sized 
to fit particular controls. Also, the height of row 9 is much greater than that of the 
other rows. The reason column 7 is so much wider and that the height of row 9 is so 
much greater is that we made them expandable. Columns and rows that are 
expandable grow when the window's size increases or shrink when the window's size 
decreases. 

When the space allotted to the canvas is larger than the size needed to contain the 
canvas, expandable rows and columns are given more space relative to each other. 

For example, if one expandable row is twice the size of another expandable row, the 
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ratio is maintained after increasing the size of the canvas. Rows and columns that are 
not specified as expandable maintain their fixed size. 

The setColumnWidth and setRowHeight functions have an expandable parameter 
whose default is false. However, we set them to true for column 7 and row 9. Here 
is the setColumnWidth function calls: 

myClient.setColumnWidth(7, 0, true); 


On the setColumnWidth function call, the first number represents column 7. The 
second number specifies the amount that the width of the column is to increase 
beyond the minimum size required for the window or windows contained in the 
column. We set this to 0 so that the column would not take up screen space unless 
the canvas is wide enough that it has space not needed by the non-expandable 
columns. The final value, true, indicates that this column is expandable. 

Positioning Push Buttons Example 

The last part of this multiple-cell canvas is actually another multiple-cell canvas. The 
two push buttons, OK and Cancel, are contained in a multiple-cell canvas that is 
nested inside the multiple-cell canvas that contains the other controls. To do this, we 
first defined a nested multiple-cell canvas called myButtons and added it to the 
bottom of the myClient multiple-cell canvas: 

myClient.addToCell(&myButtons, 2, 10, 6, 1); 


The myButtons canvas begins in column 2, row 10, and spans six columns of one 
row. Next, we used the addToCell function to put the two push buttons in the 
myButtons canvas, as follows: 

myButtons.addToCel1(&ok, 1, 1); 
myButtons.addToCel1(&cancel, 3, 1); 


The OK push button begins in column 1, row 1 of the nested canvas and occupies 
one column. In the figure, the white numbers in black boxes indicate the columns 
and rows in the nested canvas. The Cancel push button begins in column 3, row 1 of 
the nested canvas and also spans one column. The width of the columns is 
determined by the size of the text in the push buttons, together with the margin 
around the text (the space between the text and the border of the push buttons). 

You must specify the last row and column of a multiple-cell canvas on either an 
addToCell call or on setRowHeight and setColumnWidth calls. This is done to 
provide a padding, or margin, for the right and bottom sides of the canvas, similar to 
the margin provided by taking the default cell size for column 1 and row 1. The 
following are the calls used in the example to set the last column and row, column 8 
and row 11, to the default column width and row height: 

myClient.setColumnWidth(8, IMultiCellCanvas::defaultCel1().width()); 
myClient.setRowHeight(11, IMultiCel 1 Canvas::defaultCel1().height()); 
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The following points are apparent from the preceding example: 

• It is not necessary to have a window in every cell. 

• You can use empty columns and empty rows to provide padding around the 
windows. 

• The canvas can have more rows or columns than needed to hold the additional 
windows. For example, columns 1 and 8, as well as rows 1, 3, and 5, are empty. 
They will be sized either to a default value or, they can be sized explicitly by the 
application. 

• Windows can occupy multiple columns, rows, or both. The first entry field, for 
example, begins in cell (5, 4) and occupies columns 5 through 7. The number of 
columns or rows occupied includes the originating column or row. 

• A window's range can overlap cells that contain other windows. However, two 
windows cannot have the same starting cell. 


Public Functions 
Cell Contents 

Use these members to position child windows of the canvas relative to one another, in cells. 

-Specifies the starting cell into which a window is placed. Optionally, you can 
specify the number of columns or rows that the window occupies. By default, a 
multiple-cell canvas has no windows. Therefore, you must call this function to add 
windows to the canvas. 

Note: If the multiple-cell canvas is already shown, this function does not cause it to 
update the canvas itself immediately. You must call IWindow::refresh (Vol. 
II) to update the appearance of the canvas. 

You do not specify how many rows and columns a multiple-cell canvas contains. 
IMultiCellCanvas determines the maximum number of rows and columns from 
addToCell (p. 1053), setColumnWidth (p. 1059), and setRowHeight (p. 1060). 


virtual IMultiCel 1Canvas& 
addToCell( IWindow* childWindow, 

unsigned long startingColumn, 
unsigned long startingRow, 
unsigned long numberOfColumns = 1, 
unsigned long numberOfRows = 1); 


Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


IMultiCellCanvas 1053 



IMultiCellCanvas 


childWindow 

The child window that you are assigning to a cell of the canvas. If this 
window is not a child window of the canvas, the IMultiCellCanvas 
throws an IlnvalidParameter exception when it runs its layout routine. 

startingColumn 

The left-most column where the child window is placed. Columns in a 
multiple-cell canvas are numbered beginning with 1. 


startingRow 

The top-most row where the child window is placed. Rows in a 
multiple-cell canvas are numbered beginning with 1. 

numberOfColumns 

(Optional) Number of columns that the child window will span. The 
default value is 1. 

numberOjRows 

(Optional) Number of rows that the child window will span. The default 
value is 1. 


Exceptions 

IlnvalidRequest The canvas already contains a child window that begins in the cell 

identified by startingColumn and startingRow. 


removeFromCell 

Removes a window from the canvas. If you specify a cell, the window that occupies 
that cell is removed. If you specify a window, the window is removed. 

This function returns the window removed from the canvas. It does not delete the 
child window. If the specified window is not found, 0 is returned. 

You must call this function if you delete the child window or change its parent 
window. 

Note: If the multiple-cell canvas is already shown, this function does not cause it to 
update immediately. You must call IWindow::refresh (Vol. II) to update the 
appearance of the canvas. 

| virtual IWindow* 

removeFromCel 1 ( unsigned long column, 
unsigned long row); 

column The starting column of the child window being removed. Columns are 
numbered beginning with 1. This is the starting column you specified in 
the addToCell (p. 1053) call that added the child window to the canvas. 


Supported On: 

PM. Motif 
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row The starting row of the child window being removed. Rows are 

numbered beginning with 1. This is the starting row you specified in the 
addToCell (p. 1053) call that added the child window to the canvas. 

g virtual IWindow* Supported On: 

removeFromCel 1 ( IWindow* chi 1 dWindow); PM. Motif 

childWindow 

The child window to remove from the multiple-cell canvas. 

.Returns the child window occupying the specified cell. 


virtual IWindow* 

windowInCel1( unsigned long startingColumn, 

unsigned long startingRow) const; 


Supported On: 

PM, Motif 


startingColumn 

Identifier for the column. Columns in a multiple-cell canvas are 
numbered beginning with 1. 


startingRow 

Identifier for the row. Rows in a multiple-cell canvas are numbered 
beginning with 1. 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign 
IMultiCellCanvas objects because both the copy constructor and assignment operator are private 
functions. 


IMultiCellCanvas 

IMul tiCel 1 Canvas( unsigned long windowldentifier. Supported On: 

IWindow* parent, PM. Motif 

IWindow* owner, 

const IRectangle& initial Size = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

windowldentifier 

Window identifier of the canvas you construct. 

Note: For OS/2, this value is limited to the range 0 through 65535. 

It is recommended that you: 
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• Give unique identifiers to all windows in the same frame window. In 
the same window means that the frame window is the first frame in 
their parent window chain. 

• Give the client window a window ID of FID_CLIENT (0x8008). 

• Do not use the other FID_xxx values. 

parent The parent window of the canvas you construct. You must specify a 

parent window. This constructor throws an IlnvalidParameter exception 
if you pass an IWindow* of 0. The parent window is primarily used for 
visible relationships. 

owner The owner window of the canvas you construct. 

Note: In OS/2, the owner window is primarily used for routing 

notification events and unprocessed messages. OS/2 also uses the 
owner window chain to inherit colors. 

In Motif, the owner window is only used for routing unprocessed 
messages. There is no concept of an owner in Motif. 

initialSize (Optional) The initial position and size of the canvas you construct. The 
initial position is the lower-left corner of the canvas relative to the 
lower-left corner of the parent window. 

style (Optional) Use the styles provided by IMultiCellCanvas (p. 1063) Styles 

to specify the control's styles. 

IMultiCellCanvas 

virtual 

"IMultiCel 1 Canvas(); 

Grid and Drag Lines 

These members provide visual debugging aids for you to use in your IMultiCellCanvas objects. 

disableDragLines 

Removes the style IMultiCellCanvas::dragLines (p. 1063) from a multiple-cell canvas. 

virtual IMultiCel 1 Canvas& Supported On: 

di sabl eDragLines (); PM, Motif Ignored 

disableGridLines 

Removes the style IMultiCellCanvas::gridLines (p. 1063) from a multiple-cell canvas. 


Supported On: 

PM. Motif 
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virtual IMultiCel 1Canvas& 
disableGridLines(); 


Supported On: 

PM, Motif Ignored 


enableDragLines 

Sets the style IMultiCellCanvas::dragLines (p. 1063) for a multiple-cell canvas. 


virtual IMultiCel 1Canvas& 
enableDragLines( Boolean enable = true); 


Supported On: 

PM. Motif Ignored 


enableGridLines 

Sets the style IMultiCellCanvas::gridLines (p. 1063) for a multiple-cell canvas. 


virtual IMultiCel 1Canvas& 
enableGridLines( Boolean enable = true); 


Supported On: 

PM, Motif Ignored 


hasDragLines 

Queries whether a multiple-cell canvas has the style IMultiCellCanvas: :dragLines (p. 
1063) set. 


Boolean Supported On: 

hasDragLines() const; PM, Motif Ignored 

_Queries whether a multiple-cell canvas has the style IMultiCellCanvas::gridLines (p. 
1063) set. 


Boolean 

hasGridLines() const; 


Supported On: 

PM, Motif Ignored 


Layout Support 

Use layout members to determine how this class sizes and positions its child windows or how 
this window will be laid out on another canvas. 


setLayoutDistorted 

Adds the IWindow::layoutDistorted flag to its internal state if it receives a value of 
IWindow::childWindowCreated or IWindow::childWindowDestroyed and calls 
IWindow::setLayoutDistorted. If the IWindow::immediateUpdate flag is on, the 
canvas runs its layout routine. 

The internal state of a window is indicated by the Layout (Vol. II) enumeration. 
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A window treats the following events as changes to the layout of its child windows: 

• Changing the size 

• Changing the size of a child window 

• Adding another child window 

• Deleting a child window 


virtual IMultiCel 1Canvas& 
setLayoutDistorted( unsigned long 
unsigned long 


1ayoutAttributesOn, 

1ayoutAttributesOff); 


Supported On: 

PM, Motif 


Row and Column Sizing 

Use these members to query and set the width of columns and height of rows in the canvas, as 
well as to set their ability to expand with the canvas. 

- Returns the current width of the specified column, in pixels. 

unsigned long Supported On: 

columnWidth( unsigned long column) const; PM. Motif 

column Identifier of the column. Columns in a multiple-cell canvas are numbered 
beginning with 1. 

-Queries the current default cell size. The initial default size is 10 pixels by 10 
pixels. You can change it by calling the function setDefaultCell (p. 1060). 

static ISize Supported On: 

defaul tCel 1 (); PM, Motif 

isColumnExpandable 

If the specified column can be expanded when the canvas is larger than its minimum 
size, true is returned. You can use setColumnWidth (p. 1059) to make a column 
expandable. 

Bool ean Supported On: 

isColumnExpandable( unsigned long column) const; PM. Motif 

column Identifier for the column. Columns in a multiple-cell canvas are 
numbered beginning with 1. 
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isRowExpandable 

If the specified row can be expanded when the canvas is larger than its minimum 
size, true is returned. You can use setRowHeight (p. 1060) to make a row 
expandable. 

Boolean Supported On: 

isRowExpandable( unsigned long row) const; PM, Motif 

row Identifier for the row. Rows in a multiple-cell canvas are numbered 

beginning with 1. 

_ Returns the current height of the specified row, in pixels. 

unsigned long Supported On: 

rowHeight( unsigned long row) const; PM, Motif 

row Identifier for the row. Rows in a multiple-cell canvas are numbered 

beginning with 1. 


setColumnWidth 

Defines the smallest width that the column will have, and whether the column is 
expandable. The minimum sizes of the child windows in this column might cause the 
actual width of this column to be larger than this value. 

If you do not call this function, the column will have a minimum width of 0, unless 
the column contains no child windows. In that case, the canvas sizes the column to 
the default cell width. 

You do not specify how many rows and columns a multiple-cell canvas contains. 
IMultiCellCanvas determines the maximum number of rows and columns from 
addToCell (p. 1053), setColumnWidth (p. 1059), and setRowHeight (p. 1060). 

Note: If the multiple-cell canvas is already shown, this function does not cause it to 
update immediately. You must call IWindow::refresh (Vol. II) to update the 
appearance of the canvas. 

virtual IMultiCel 1Canvas& 

setColumnWidth( unsigned long column, 

unsigned long widthlnPixels, 

Boolean expandable = false); 

column Identifier for the column. Columns in a multiple-cell canvas are 
numbered beginning with 1. 


Supported On: 

PM, Motif 
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widthlnPixels 

Minimum width in pixels. 


expandable 

(Optional) If set to true, windows in the column are expanded 
horizontally when the canvas is larger than its minimum size. The 
default is false. 


setDefaultCell 

Sets the default width for a column and height for a row of a cell that does not have 
a child window. The initial default size for both rows and columns is 10 pixels. 

Note: This function does not cause the layout of a multiple-cell canvas to update the 
canvas itself immediately. To force a multiple-cell canvas to update after 
calling this function, call setLayoutDistorted (p. 1057), as follows: 

setLayoutDistorted(IWindow::1ayoutChanged | 

IWindow::immediateUpdate, 0); 

static void Supported On: 

setDefaul tCel 1 ( const ISize& widthAndHeight); PM, Motif 


setRowHeight 

Defines the smallest height that the row will have, and whether the row is 
expandable. The minimum sizes of the child windows in this row can cause the 
actual height of the row to be larger than this value. 

If you do not call this function, the row will have a minimum height of 0, unless the 
row contains no child windows. In that case, the canvas sizes the row to the default 
cell height. 

You do not specify how many rows and columns a multiple-cell canvas contains. 
IMultiCellCanvas determines the maximum number of rows and columns from 
addToCell (p. 1053), setColumnWidth (p. 1059), and setRowHeight (p. 1060). 

Note: If a multiple-cell canvas is already shown, this function does not cause it to 
update the canvas itself immediately. You must call IWindow::refresh (Vol. 
II) to update the appearance of the canvas. 

virtual IMultiCel 1Canvas& 
setRowHeight( unsigned long row, 

unsigned long heightlnPixels, 

Boolean expandable = false); 

row Identifier for the row. Rows in a multiple-cell canvas are numbered 

beginning with 1. 


Supported On: 

PM, Motif 
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heightlnPixels 

Minimum height in pixels. 

expandable 

(Optional) If set to true, windows in the row are expanded vertically 
when the canvas is larger than its minimum size. The default is false. 


Styles 

Use these style members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 
You can use these styles with the styles defined by the following nested classes: 

ICanvas::Styles (p. 34) 

IWindow:: Styles (Vol. II) 

Once you have constructed an IMultiCellCanvas object, you can use IMultiCellCanvas, ICanvas, 
and IWindow member functions to query and change its style. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

-.Returns the default style. The default style is classDefaultStyle (p. 1063) unless you 
have changed the style using setDefaultStyle (p. 1061). 

static Style Supported On: 

defaul tStyle(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent multiple-cell canvases. 

static void Supported On: 

setDefaultStyle( const Style& style); PM, Motif 

style A combination of IMultiCellCanvas::Style (p. 1063), ICanvas::Style (p. 

34), and IWindow::Style (Vol. II) objects. 
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Inherited Public Functions 


ICanvas 

backgroundColor 

defaultStyle 

origDefaultButtonHandle 

convertToGUIStyle 

isTabStop 

setDefaultStyle 

defaultPushButton 

matchForMnemonic 

setLayoutDistorted 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Layout Support 

Use layout members to determine how this class sizes and positions its child windows or how 
this window will be laid out on another canvas. 

.Computes the child windows' positions and sizes based on: 

• The contents of the cells 

• The minimum size of rows and columns 

• The expandability of rows and columns 

virtual IMultiCel1Canvas& 
layout(); 


Supported On: 

PM. Motif 
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Inherited Protected Functions 


ICanvas 

areChildrenReversed 

layout 

registerCallbacks 

calcMinimumSize 

layoutSize 

setLay outSize 

fixupChildren 

passEventT oOwner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
Styles 

Use these style members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 
You can use these styles with the styles defined by the following nested classes: 

ICanvas::Styles (p. 34) 

IWindow::Styles (Vol. II) 

Once you have constructed an IMultiCellCanvas object, you can use IMultiCellCanvas, ICanvas, 
and IWindow member functions to query and change its style. 


classDefaultStyle 

Specifies the original default style for this class, which is IWindow::visible. 

static const Style Supported On: 

classDefaultStyle; PM, Motif 

_Causes the multiple-cell canvas to have draggable grid lines between the rows and 
columns of the canvas. 


static const Style Supported On: 

drag Lines; PM. Motif 

..Causes the multiple-cell canvas to have grid lines between the rows and columns of 
the canvas. 
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static const Style 
gridLines; 


Supported On: 

PM, Motif 


Inherited Public Data 


ICanvas 

classDefaultStyle 




IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

dipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoiorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IMultiCellCanvas contains the following nested classes: 
IMultiCellCanvas::Style (see page 1065) 
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IMultiCellCanvas::Style 


IBase 

IBitFlag 

IMultiCellCanvas::Style 


_.None. 

_.imcelcv.hpp 

The nested class IMultiCellCanvas::Style provides a set of valid multiple-cell canvas 
styles for IMultiCellCanvas::defaultStyle, IMultiCellCanvas::setDefaultStyle, and the 
constructor of the IMultiCellCanvas (p. 1049) class. 

| Motif dragLines and gridLines are not supported in the AIX release. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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INotebook 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

INotebook 


_.None. 

_i notehk. lipp 


Member 

Page 

Member 

Page 

Constructor 

1072 

nextPage 

1078 

addFirstPage 

1074 

notebooks ize 

1080 

addLastPage 

1075 

orientation 

1074 

addPageAfter 

1075 

orientationld 

1091 

addPageBefore 

1076 

pageB ackgroundColor 

1069 

backgroundColor 

1068 

pageB ackgroundColorld 

1091 

backPage sB ottomLeft 

1092 

pageSettings 

1077 

backPagesBottomRight 

1092 

pageSize 

1080 

backPagesTopLeft 

1092 

pagesToEnd 

1081 

backPagesTopRight 

1092 

pagesToMajorTab 

1081 

binding 

1068 

pagesToMinorTab 

1081 

calcMinimumSize 

1090 

polygonTabs 

1094 

classDefaultStyle 

1093 

previousPage 

1078 

con vertT oGUISty le 

1085 

refreshTabs 

1086 

defaultStyle 

1085 

registerCallbacks 

1089 

enableNotification 

1073 

removeAllPages 

1079 

firstPage 

1078 

removePage 

1079 

hiliteBackgroundColor 

1069 

removeTabSection 

1079 

isEmpty 

1080 

re setMaj orT abB ackgroundColor 

1070 

lastPage 

1078 

resetMajorTabForegroundColor 

1070 

maj orT abB ackgroundColor 

1069 

re setMinorTabB ackgroundColor 

1070 

maj orT abB ackgroundColorld 

1090 

resetMinorTabForegroundColor 

1070 

maj orTabForegroundColor 

1069 

re setPageB ackgroundColor 

1070 

maj orTabForegroundColorld 

1091 

roundedTabs 

1094 

majorTabsBottom 

1093 

setB ackgroundColor 

1071 

majorTabsLeft 

1093 

setBinding 

1068 

majorTabsRight 

1093 

setDefaultStyle 

1085 

majorTabsTop 

1093 

setForegroundColor 

1071 

minorTabB ackgroundColor 

1069 

setMaj orT abB ackgroundColor 

1071 

minorTabB ackgroundColorld 

1091 

setMaj orTabForegroundColor 

1071 

minorT abForegroundColor 

1069 

setMaj orTabSize 

1086 

minorT abForegroundColorld 

1091 

setMinorT abB ackgroundColor 

1071 
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Member 

Page 

Member 

Page 

setMinorTabForegroundColor 

1071 

statusTextAlignment 

1084 

setMinorT abS ize 

1086 

statusT extCenter 

1094 

setOrientation 

1074 

statusTextLeft 

1094 

setPageB ackgroundColor 

1072 

statusTextRight 

1094 

setPageButtonSize 

1077 

tabShape 

1088 

setStatusText 

1083 

tabText Alignment 

1088 

setS tatusT ext Alignment 

1084 

tabTextCenter 

1095 

setTabBitmap 

1086 

tabTextLeft 

1095 

setTabShape 

1087 

tabTextRight 

1095 

setTabText 

1087 

topPage 

1078 

setTabTextAlignment 

1088 

totalPages 

1082 

setUserData 

1068 

turnToPage 

1078 

setWindow 

1082 

unregisterCallbacks 

1090 

solidBinding 

1094 

window 

1083 

spiralBinding 

1094 

“INotebook 

1073 

squareTabs 

1094 




The INotebook class is a wrapper for the notebook control. The notebook is a control 
that is useful in organizing related information on individual pages so that a user can 
quickly find and display the information. Use an object of this class to create and 
manage a notebook control. 

A notebook control consists of the following items, and this class provides member 
functions that support each of these items: 

• A notebook client area 

• A binding 

• Page buttons 

• Optional tabs 

• An optional status area 

When working with objects of this class, you can also use the following nested 
classes: 

• INotebook::PageSettings (p. 1102), whose objects define the characteristics of a 
page when it is added to a notebook 

• INotebook::Cursor (p. 1098), whose objects iterate through the pages of the 
notebook 


Public Functions 
Application Data 

Use these members to set the application data associated with a notebook page. 
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— Sets the application data into the specified page's reserved storage. Each page has a 
4-byte reserved storage area. This area is available for information required by your 
application. 


virtual INotebook& 

setUserData( const IPageHandle& referencePage, 
unsigned long userData); 


Supported On: 

PM. Motif 


referencePage 

Reference to the handle of a notebook page. 

userData Unsigned long value that represents the application data to be set into the 
specified page's storage. 


Exceptions 

IAccessError The user data was not set for the specified page. The page identifier (ID) 

of the notebook page may be invalid. 


Binding Support 

Use these members to query and set the notebook's binding. 

-Returns the type of binding used for the notebook. The return value is a Binding (p. 
1097) enumerator. 


virtual Binding Supported On: 

binding() const; PM. Motif 

_Sets the type of binding for the notebook. 


virtual INotebook& Supported On: 

setBinding( Binding binding); PM. Motif 

binding Binding (p. 1097) enumeration that specifies the binding type. 


Exceptions 

IlnvalidParameter The binding style was not set. The binding parameter is invalid. 


Colors 

Use these members to set and query the color of different areas of the notebook. 


backgroundColor 

Returns the background color of the notebook or the default if you have not set it. 
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virtual IColor Supported On: 

backgroundColor() const; PM, Motif 

hiliteBackgroundColor 

Returns the notebook's highlight background color or the default color value if no 
highlight background color for the notebook has been set. 


virtual IColor Supported On: 

hi 1 i teBackgroundColor() const; PM, Motif Ignored 

majorTabBackgroundColor 

Returns the major tab background color of the notebook or the default if you have not 
set it. 


virtual IColor Supported On: 

majorTabBackgroundColor() const; PM 

majorTabForegroundColor 

Returns the major tab foreground color of the notebook or the default if you have not 
set it. 


virtual IColor Supported On: 

majorTabForegroundColor() const; PM 

minorTabBackgroundColor 

Returns the minor tab background color of the notebook or the default if you have 
not set it. 


virtual IColor Supported On: 

minorTabBackgroundColor() const; PM 

minorTabForegroundColor 

Returns the minor tab foreground color of the notebook or the default if you have not 
set it. 


virtual IColor 

minorTabForegroundedor() const; 


Supported On: 

PM 


pageBackgroundColor 

Returns the page background color of the notebook or the default if you have not set 
it. 
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virtual IColor Supported On: 

pageBackgroundColor() const; PM 

resetMajorTabBackgroundColor 

Resets the major tab background color by changing to the major tab background color 
that was previously set. 


virtual INotebook& Supported On: 

resetMajorTabBackgroundCol or() ; PM, Motif Ignored 

resetMajorTabForegroundColor 

Resets the major tab foreground color by changing to the major tab foreground color 
that was previously set. 


virtual INotebook& Supported On: 

resetMajorTabForegroundCol or() ; PM, Motif Ignored 

resetMinorTabBackgroundColor 

Resets the minor tab background color by changing to the minor tab background 
color that was previously set. 


virtual INotebook& Supported On: 

resetMinorTabBackgroundColorQ ; PM, Motif Ignored 

resetMinorTabForegroundColor 

Resets the minor tab foreground color by changing to the minor tab foreground color 
that was previously set. 


virtual INotebook& 
resetMinorTabForegroundColor(); 


Supported On: 

PM, Motif Ignored 


resetPageBackgroundColor 

Resets the page background color by changing to the page background color that was 
previously set. 


virtual INotebook& 
resetPageBackgroundColor(); 


Supported On: 

PM, Motif Ignored 
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setBackgroundColor 

Sets the notebook's background color. 


virtual INotebook& Supported On: 

setBackgroundColor( const IColor& color); Motif 

color Reference to a color object that defines the new background color. 


setForegroundColor 

Sets the notebook's foreground color. 

virtual INotebook& Supported On: 

setForegroundColor( const IColor& color); Motif 

color Reference to a color object that defines the new foreground color. 

setMajorTabBackgroundColor 

Sets the major tab background color. 

virtual INotebook& Supported On: 

setMajorTabBackgroundColor( const IColor& color); PM 

color Reference to a color object that defines the major tab background color. 

setMajorTabForegroundColor 

Sets the major tab foreground color. 

virtual INotebook& Supported On: 

setMajorTabForegroundColor( const IColor& color); PM 

color Reference to a color object that defines the major tab foreground color. 

setMinorTabBackgroundColor 

Sets the minor tab background color. 

virtual INotebook& Supported On: 

setMinorTabBackgroundColor( const IColor& color); PM 

color Reference to a color object that defines the minor tab background color. 

setMinorTabForegroundColor 

Sets the minor tab foreground color. 
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virtual INotebook& Supported On: 

setMinorTabForegroundColor( const IColor& color); PM 

color Reference to a color object that defines the minor tab foreground color. 

setPageBackgroundColor 

Sets the page background color. 

virtual INotebook& Supported On: 

setPageBackgroundColor( const IColor& color); PM 

color Reference to a color object that defines the page background color. 

Constructors 

You can construct and destruct objects of this class. This class supports the same three standard 
constructors that all of the control classes in the User Interface Class Library support. 

Note: Typically, you create notebooks as clients of frame windows. Use 

IFrameWindow::setClient (Vol. II) to make the notebook the client of a frame window. 

INotebook 

2 INotebook( unsigned long windowld, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

windowld Unsigned long value that represents the notebook control identifier (ID). 

parent Pointer to the parent window object. 

owner Pointer to the owner window object. 

initial Reference to a rectangle object. It specifies the initial position and size 
of the notebook. The default size and position are determined by the 
default constructor for IRectangle (Vol. I). Optional. 

style (Optional) Use the styles provided by INotebook (p. 1090) Styles to 

specify the control's styles. 

Use this version of the constructor to create a new notebook control window and a 
corresponding INotebook object. 


Supported On: 

PM, Motif 
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Exceptions 

IlnvalidParameter The notebook object was not created. The creation failed because the 

pointer to the parent window object cannot be 0. 


§ INotebook( unsigned long windowld, Supported On: 

IWindow* parentAndOwner); PM 

windowld Unsigned long value that represents the notebook control identifier (ID). 

parentAndOwner 

Pointer to the parent and owner window object. 

Use this version of the constructor if you want to wrapper a notebook control that is 
loaded from a dialog resource. 

Note: Loading a notebook control from a dialog resource limits the capability of the 
notebook because page windows cannot be specified within a dialog template. 

Exceptions 

IlnvalidParameter The notebook object was not created. The creation failed because the 

pointer to the parent and owner window object cannot be 0. 

g INotebook( const IWindowHandle& handle); Supported On: 

PM 

handle Reference to a window handle of an existing notebook control. 

Use this version of the constructor to wrapper an existing notebook control window. 

INotebook 

This destructor destroys the notebook control window only if the User Interface Class 
Library created it. 

virtual Supported On: 

'INotebookO; PM. Motif 


Notification Members 

Use these INotificationld (Vol. I) strings for all notifications that INotebook provides to its 
observers. 

enableNotification 

Enables the notebook to send notifications to any observer objects. 
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virtual IWindow& Supported On: 

enableNotification( Boolean enable = true); PM, Motif 

enable Boolean value that specifies if the observer notification is enabled. The 
default is true. 


Orientation 

Use these members to query and set the orientation of the corner of the back pages of a notebook 
in relation to the location of the major tabs. 

Note: The back pages are the recessed edges that give the notebook a three-dimensional effect. 

-Returns the current orientation of the notebook, which is the location of the major 
tabs in relation to the back pages' corner. The return value is an Orientation (p. 

1096) enumerator. 

virtual Orientation Supported On: 

orientation() const; PM. Motif 


setOrientation 

Sets the orientation of the back pages' corner in relation to the location of the major 
tabs. 


virtual INotebook& Supported On: 

setOrientation( Orientation orientation); PM. Motif 

orientation Orientation (p. 1096) enumeration that specifies the orientation of the 
back pages' corner in relation to the location of the major tabs. 


Exceptions 

IlnvalidParameter The orientation style was not set. The orientation parameter is invalid. 


Page Addition 

Use these members to add a page to a notebook. 

_..Adds a page as the first page in the notebook using the specified page settings. If 
pageWindow is 0, a page with the indicated settings, but no application page window, 
is added to the notebook. 

Note: When adding an IFrameWindow (Vol. II) as a notebook page, create an 
IFrameWindow with the notebook as its parent. 
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virtual IPageHandle Supported On: 

addFi rstPage( const PageSettings& pagelnfo, PM, Motif 

IWindow* pageWindow = 0); 

pagelnfo Reference to an INotebook::PageSettings (p. 1102) object. Use this 
object to specify the new page's settings. 

pageWindow 

Pointer to the window object to use as the application page window. The 
default is 0. 

-. Adds a page as the last page in the notebook using the specified page settings. If 
pageWindow is 0, a page with the indicated settings, but no application page window, 
is added to the notebook. 

Note: When adding an IFrameWindow (Vol. II) as a notebook page, create an 
IFrameWindow with the notebook as its parent. 


virtual IPageHandle 

addLastPage( const PageSettings& pagelnfo, 
IWindow* pageWindow = 0); 


Supported On: 

PM, Motif 


pagelnfo Reference to an INotebook::PageSettings (p. 1102) object. Use this 
object to specify the new page's settings. 


pageWindow 

Pointer to the window object to use as the application page window. The 
default is 0. 


addPageAfter 

Adds a page to the notebook following the specified page using the specified page 
settings. If pageWindow is 0, a page with the indicated settings, but no application 
page window, is added to the notebook. 

Note: When adding an IFrameWindow (Vol. II) as a notebook page, create an 
IFrameWindow with the notebook as its parent. 

| virtual IPageHandle 

addPageAfter( const PageSettings& pagelnfo, 
const Cursor& cursor, 

IWindow* pageWindow = 0); 

pagelnfo Reference to an INotebook::PageSettings (p. 1102) object. Use this 
object to specify the new page's settings. 

cursor Reference to a cursor object that points to a notebook page. The new 
page is added after this page. 


Supported On: 

PM, Motif 
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pageWindow 

Pointer to the window object to use as the application page window. The 
default is 0. 


g virtual IPageHandle Supported On: 

addPageAfter( const PageSettings& pagelnfo, PM, Motif 

const IPageHandle& referencePage, 

IWindow* pageWindow = 0); 

pagelnfo Reference to an INotebook: :PageSettings (p. 1102) object. Use this 
object to specify the new page's settings. 

referencePage 

Reference to the handle of a notebook page. The new page is added after 
this page. 

pageWindow 

Pointer to the window object to use as the application page window. The 
default is 0. 


addPageBefore 

Adds a page to the notebook before the specified page using the specified page 
settings. If pageWindow is 0, a page with the indicated settings, but no application 
page window, is added to the notebook. 

Note: When adding an IFrameWindow (Vol. II) as a notebook page, create an 
IFrameWindow with the notebook as its parent. 


[J virtual IPageHandle Supported On: 

addPageBefore( const PageSettings& pagelnfo, PM, Motif 

const Cursor& cursor, 

IWindow* pageWindow = 0); 

pagelnfo Reference to an INotebook: :PageSettings (p. 1102) object. Use this 
object to specify the new page's settings. 

cursor Reference to a cursor object that points to a notebook page. The new 
page is added before this page. 

pageWindow 

Pointer to the window object to use as the application page window. The 
default is 0. 

g virtual IPageHandle Supported On: 

addPageBefore( const PageSettings& pagelnfo, PM, Motif 

const IPageHandle& referencePage, 

IWindow* pageWindow = 0); 
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pagelnfo Reference to an INotebook::PageSettings (p. 1102) object. Use this 
object to specify the new page's settings. 

referencePage 

Reference to the handle of a notebook page. The new page is added 
before this page. 

pageWindow 

Pointer to the window object to use as the application page window. The 
default is 0. 


Page Button 

Use these members to set the page button's size. 


setPageButtonSize 

Sets the size in pixels of the page (arrow) buttons that are used to turn the notebook's 
pages. 

virtual INotebook& Supported On: 

setPageButtonSize( const ISize& sizePageButton); PM. Motif Ignored 

sizePageButton 

Reference to a size object that represents the new size for page buttons. 


Exceptions 

IAccessError The page button size was not set. The page button dimensions may be 

invalid. 


Page Information 

Use these members to obtain information on a notebook page. 
.. Returns information about the specified page. 


Q PageSettings Supported On: 

pageSettings( const IPageHandle& page) const; PM. Motif 

page Reference to the handle of the notebook page to obtain information for. 


g PageSettings Supported On: 

pageSettings( const Cursor& cursor) const; PM. Motif 

cursor Reference to a cursor object that points to the notebook page to obtain 
information for. 
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Page Manipulation 

Use these members to manipulate pages within a notebook. 

-Returns an IPageHandle (p. 1121) object that references the first page in the 
notebook. 


virtual IPageHandle Supported On: 

firstPageO const; PM. Motif 

.Returns an IPageHandle (p. 1121) object that references the last page in the 

notebook. 


virtual IPageHandle Supported On: 

lastPage() const; PM. Motif 

.Returns an IPageHandle (p. 1121) object that references the page following the 
specified page. 


virtual IPageHandle Supported On: 

nextPage( const IPageHandle& referencePage) const; PM. Motif 

referencePage 

Reference to the handle of the notebook page that precedes the page you 
want to access. 


previousPage 

Returns an IPageHandle (p. 1121) object that references the page before the specified 
page. 


virtual IPageHandle Supported On: 

previousPage( const IPageHandle& referencePage) const; PM. Motif 

referencePage 

Reference to the handle of the notebook page that follows the page you 
want to access. 

.Returns an IPageHandle (p. 1121) object that references the current top page of the 

notebook. 


virtual IPageHandle Supported On: 

topPage() const; PM. Motif 

__Moves a specified page to the top of the notebook. 
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Q virtual INotebook& Supported On: 

turnToPage( const Cursor& cursor); PM, Motif 

cursor Reference to a cursor object that points to the notebook page to move to 
the top of the notebook. 


@ virtual INotebook& Supported On: 

turnToPage( const IPageHandle& page); PM. Motif 

page Reference to the handle of the notebook page to move to the top of the 

notebook. 


Exceptions 

IAccessError The specified page window was not moved to the top of the notebook. 

The page identifier (ID) of the specified page may be invalid. 


Page Removal 

Use these members to remove a page or pages from a notebook. 

removeAMPages 

Removes all the pages in the notebook. 

virtual INotebook& Supported On: 

removeAl 1 Pages (); PM, Motif 

-.Removes the specified page from the notebook. 

0 virtual INotebook& 

removePage( const IPageHandle& page); 

page Reference to the handle of the notebook page to remove. 

§ virtual INotebook& Supported On: 

removePage( const Cursor& cursor); PM, Motif 

cursor Reference to a cursor object that points to the notebook page to remove. 

removeTabSection 

If the specified page is a major tab page, it removes the specified page and all 
subsequent pages up to the next major tab page. If the specified page is a minor tab 
page, it removes the specified page and all subsequent pages up to the next page that 
has a tab. 


Supported On: 

PM, Motif 
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[J virtual INotebook& Supported On: 

removeTabSection( const IPageHandle& page); PM, Motif 

page Reference to the handle of the notebook page. This page is at the 

beginning of the section to remove. 

Exceptions 

IlnvalidRequest The notebook tab section was not removed. The removal failed because 

the specified notebook page is not associated with a major or a minor tab. 


2 virtual INotebook& Supported On: 

removeTabSection( const Cursor& cursor); PM, Motif 

cursor Reference to a cursor object that points to the notebook page. This page 
is at the beginning of the section to remove. 


Page Support 

Use these members to support page counting and to determine size information for the notebook. 
_ Queries whether the notebook has any pages, and returns true if it is empty. 


virtual Boolean 
isEmptyO const; 


Supported On: 

PM. Motif 


notebookSize 

Returns the size that the notebook must be in order to contain the specified page. 
The notebook size if calculated based on the size of the page window, or its 
minimum size if it has no size. 


virtual ISize Supported On: 

notebookSize( const IPageHandle& page) const; PM, Motif 

page Reference to the handle of the notebook page that the size is based on. 


Exceptions 

IAccessError The notebook size was not returned. The coordinates of the application 

page window may be invalid. 


.. Returns the size of the notebook's pages. All notebook pages have the same size. 
Application windows associated with notebook pages can use this information to 
determine their size. 
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virtual ISize 
pageSize() const; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The page's size was not returned. The coordinates of the notebook window 

may be invalid. 


_Returns the number of pages in the notebook from a specified notebook page to the 
end of the notebook. This value includes the specified page. 


| virtual unsigned long 

pagesToEnd( const IPageHandle& page) const; 

page Reference to the handle of the notebook page. 


Supported On: 

PM, Motif 


§ virtual unsigned long 

pagesToEnd( const Cursor& cursor) const; 


Supported On: 

PM, Motif 


cursor Reference to a cursor object that points to the notebook page. 


pagesToMajorTab 

Returns the number of pages in the notebook between a specified notebook page and 
the next page that has a major tab. This value does not included the specified page. 


| virtual unsigned long 

pagesToMajorTab( const IPageHandle& page) const; 

page Reference to the handle of the notebook page. 


Supported On: 

PM, Motif 


§ virtual unsigned long 

pagesToMajorTab( const Cursor& cursor) const; 


Supported On: 

PM, Motif 


cursor Reference to a cursor object that points to the notebook page. 


pagesToMinorTab 

Returns the number of pages in the notebook between a specified notebook page and 
the next page that has a minor tab. This value does not include the specified page. 

Q virtual unsigned long Supported On: 

pagesToMinorTab( const Cursor& cursor) const; PM, Motif 

cursor Reference to a cursor object that points to the notebook page. 
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g virtual unsigned long Supported On: 

pagesToMinorTab( const IPageHandle& page) const; PM, Motif 

page Reference to the handle of the notebook page. 

.Returns the total number of pages in the notebook. 


virtual unsigned long 
totalPages() const; 


Supported On: 

PM. Motif 


Page Window Association 

Use these members to query and set the application page window that is associated with the 
specified notebook page. 

-..Associates the specified note page with the application page window. 

Note: If you use a page selection handler to delay creating an application page 

window to associate with a notebook page, you can call this function in the 
selection handler routine. 


[J virtual INotebook& Supported On: 

setWindow( const IPageHandle& referencePage, PM, Motif 

IWindow* pageWindow = 0); 

referencePage 

Reference to the handle of the notebook page. 
pageWindow 

Pointer to the window object to use as the application page window. The 
default is 0. 


Exceptions 

IAccessError The specified page was not associated with the window. The page 

identifier (ID) of the notebook page may be invalid. 


2 virtual INotebook& Supported On: 

setWindow( const Cursor& cursor, PM, Motif 

IWindow* pageWindow = 0); 

cursor Reference to a cursor object that points to the notebook page. 
pageWindow 

Pointer to the window object to use as the application page window. The 
default is 0. 
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Returns the application page window associated with the specified notebook page. 


Q virtual IWindow* Supported On: 

window( const IPageHandle& page) const; PM. Motif 

page Reference to the handle of the notebook page. 


Exceptions 

IAccessError The window associated with the specified notebook page was not returned. 

The page identifier (ID) of the specified notebook page may be invalid. 


§ virtual IWindow* Supported On: 

window( const Cursor& cursor) const; PM. Motif 

cursor Reference to a cursor object that points to the notebook page. 


Status Text 

Use these members to query and set the status text alignment, and to set the status text. 


setStatusText 

Sets the status text for the specified page of the notebook. 

2 virtual INotebook& Supported On: 

setStatusText( const IPageHandle& referencePage, PM, Motif 

const IResourceId& resourceld); 


referencePage 

Reference to the handle of the specified notebook page. 

resourceld Reference to a resource identifier object that identifies the text to use on 
the status line of the specified notebook page. 


§ virtual INotebook& Supported On: 

setStatusText( const IPageHandle& referencePage, PM, Motif 

const char* statusText); 

referencePage 

Reference to the handle of the specified notebook page. 


statusText Pointer to the text to use on the status line of the specified notebook 
page. 
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Exceptions 

IAccessError 

The status text was not set for the specified page. The page identifier (ID) 
of the notebook page may be invalid. 

IlnvalidRequest 

The page does not have a status line to display the text. You must specify 
the INotebook: :PageSettings::statusTextOn attribute when adding the page 
to the notebook. 


setStatusTextAlignment 

Sets the alignment of the text in the notebook's status line. 


virtual INotebook& Supported On: 

setStatusTextAl ignment( TextAl ignment alignment); PM. Motif 

alignment TextAlignment (p. 1097) enumeration that specifies the alignment of the 
status text. 


Exceptions 

IlnvalidParameter The alignment style of the status text line was not set. The alignment 

parameter is invalid. 


statusTextAlignment 

Returns the alignment of the text in the notebook's status line. The return value is a 
TextAlignment (p. 1097) enumerator. 


virtual TextAlignment 
statusTextAlignment() const; 


Supported On: 

PM. Motif 


Styles 

Use these members to set and query the various styles that are associated with a notebook. You 
can use these styles with the styles defined by the following nested classes: 

IWindow::Styles (Vol. II) 

IControl::Styles (Vol. II) 

The combination of styles you specify for the back pages (the recessed edges that give the 
notebook a three-dimensional effect) and the major tabs determines how the pages in the 
notebook look and behave when the user iterates through the notebook's pages. 

An object of this nested class is provided when you create a notebook. A customizable default is 
used if you do not specify any styles. Once the notebook object is created, you can use 
INotebook, IWindow, and IControl member functions to set or query the object's style. 
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The declaration of the INotebook::Style nested class is generated by the 
INESTEDBITFLAGCLASSDEF2 macro. 

convertToGUIStyle 

Converts style bits into the style value that can be processed by the graphical user 
interface (GUI). The default action is to return the base GUI style for the platform. 
Extended styles that either the User Interface Class Library has defined or you have 
defined can be returned by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

style Reference to a bit flag object that defines the graphical user interface 

(GUI) style. 

extendedOnly 

Boolean value that specifies to return only the extended styles. 

-.Returns the default style. The default style is classDefaultStyle (p. 1093) unless you 
have changed the style using setDefaultStyle (p. 1085). 

static Style Supported On: 

defaul tStyl e(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent notebooks. 

static void Supported On: 

setDefaultStyle( const Style& style); PM, Motif 

style Reference to a style object that defines the default style. Use the styles 

provided by INotebook (p. 1090) Styles to specify the default style. 


Tab Support 

Use these members to provide the following tab support: 

• Query and set the tab shape 

• Query and set the tab text alignment 

• Set the size of the major notebook tabs 

• Set the size of the minor notebook tabs 

• Refresh (repaint) all of the notebook's tabs 

• Set the tab's text 
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• Set the tab's bitmap 

. .Causes all of the notebook's visible tabs to be repainted. 


virtual INotebook& 
refreshTabs(); 


Supported On: 

PM. Motif 


Exceptions 

IAccessError The tabs were not repainted. An error occurred within the notebook 

control. 


setMajorTabSize 

Sets the size of the notebook's major tabs in pixels. 


virtual INotebook& Supported On: 

setMajorTabSize( const ISize& sizeMajorTab) ; PM, Motif Ignored 

sizeMajorTab 

Reference to a size object that represents the new size for the major tabs. 


Exceptions 

IAccessError The major tab size was not set. The tab dimensions may be invalid. 


setMinorTabSize 

Sets the size of the notebook's minor tabs in pixels. 


virtual INotebook& Supported On: 

setMinorTabSize( const ISize& sizeMinorTab) ; PM, Motif Ignored 

sizeMinorTab 

Reference to a size object that represents the new size for minor tabs. 


Exceptions 

IAccessError The minor tab size was not set. The tab dimensions may be invalid. 


setTabBitmap 

Sets the tab bitmap for the specified page of the notebook. 

[J virtual INotebook& Supported On: 

setTabBitmap( const IPageHandle& referencePage, PM, Motif 

const IBitmapHandle& bitmap); 
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referencePage 

Reference to the handle of the specified notebook page. 

bitmap Reference to the handle of the bitmap to use on the tab of the specified 
notebook page. 


Exceptions 

IAccessError The tab bitmap was not set for the specified page. The page identifier (ID) 

of the notebook page may be invalid or the page may be missing the major 
or minor tab attribute. 


g virtual INotebook& 

setTabBitmap( const IPageHandle& referencePage, 
const IResourceId& resourceld); 


Supported On: 

PM, Motif 


referencePage 

Reference to the handle of the specified notebook page. 

resourceld Reference to a resource identifier object that identifies the bitmap to use 
on the tab of the specified notebook page. 


...Sets the shape of the notebook's tabs. 


virtual INotebook& Supported On: 

setTabShape( TabShape tabShape); PM. Motif Ignored 

tabShape TabShape (p. 1097) enumeration that specifies the shape of the tab. 


Exceptions 

IlnvalidParameter The tab shape style was not set. The tabShape parameter is invalid. 


Sets the tab text for the specified page of the notebook. 


| virtual INotebook& 

setTabText( const IPageHandle& referencePage, 
const IResourceId& resourceld); 


Supported On: 

PM, Motif 


referencePage 

Reference to the handle of the specified notebook page. 

resourceld Reference to a resource identifier object that identifies the text to use on 
the tab of the specified notebook page. 
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2 virtual INotebook& 

setTabText( const IPageHandle& referencePage, 
const char* tabText); 


Supported On: 

PM, Motif 


referencePage 

Reference to the handle of the specified notebook page. 
tabText Pointer to the text to use on the tab of the specified notebook page. 


Exceptions 

IAccessError The tab text was not set for the specified page. The page identifier (ID) of 

the notebook page may be invalid or the page may be missing the major or 
minor tab attribute. 


setTabTextAlignment 

Sets the alignment of the text in the notebook's tabs. 


virtual INotebook& Supported On: 

setTabTextAl ignment( TextAl ignment alignment); PM. Motif 

alignment TextAlignment (p. 1097) enumeration that specifies the alignment of the 
tab text. 


Exceptions 

IlnvalidParameter The tab text alignment style was not set. The alignment parameter is 

invalid. 


.Returns the shape of the notebook's tabs. The return value is a TabShape (p. 1097) 

enumerator. 


virtual TabShape Supported On: 

tabShape() const; PM, Motif Ignored 

tabTextAlignment 

Returns the alignment of the text in the notebook's tabs. The returned value is a 
TextAlignment (p. 1097) enumerator. 

virtual TextAlignment Supported On: 

tabTextAl ignment() const; PM. Motif 
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Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Event-Handling Implementation 

Use these members to add and remove callback functions for events that a notebook might 
receive. 

registerCailbacks 

Registers all possible callbacks and X event handlers to an object of this class for 
events it might receive. IHandler (Vol. II) derived classes later determine which 
events they process. 

Note: If classes you derive override this member function, the override must call 
Inherited::registerCallbacks to register the applicable callbacks and X event 
handlers. 

virtual void Supported On: 

regi sterCall backs (); Motif 
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unregisterCallbacks 

Unregisters Motif callbacks for the widgets created during object construction of this 
class. 


virtual void 
unregi sterCal1 backs(); 


Supported On: 

Motif 


Layout Support 

Use these members to support the layout of a notebook within a canvas. 


calcMinimumSize 

Returns the minimum recommended size for this notebook. This size is large enough 
to contain the largest application page window that is currently in the notebook. This 
function calls notebookSize (p. 1080). 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM. Motif 


Exceptions 

IAccessError The minimum size was not calculated. The coordinates of the notebook or 

application page window may be invalid. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 

Notification Members 

Use these INotificationld (Vol. I) strings for all notifications that INotebook provides to its 
observers. 

majorTabBackgroundColorld 

Notification identifier provided to observers when the major tab background color of 
the notebook control changes. 
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static INotificationld const Supported On: 

majorTabBackgroundColorld; PM, Motif 

majorTabForegroundColorld 

Notification identifier provided to observers when the major tab foreground color of 
the notebook control changes. 

static INotificationld const 
majorTabForegroundColorld; 

minorTabBackgroundColorld 

Notification identifier provided to observers when the minor tab background color of 
the notebook control changes. 

static INotificationld const 
minorTabBackgroundColorld; 

minorTabForegroundColorld 

Notification identifier provided to observers when the minor tab foreground color of 
the notebook control changes. 

static INotificationld const Supported On: 

minorTabForegroundColorld; PM, Motif 

-.Notification identifier provided to observers when the orientation style of the 
notebook control changes. INotebook provides the new orientation value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is one of the predefined Orientation enumeration values defined in this class. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


static INotificationld const 
orientationld; 


Supported On: 

PM, Motif 


pageBackgroundColorld 

Notification identifier provided to observers when the page background color of the 
notebook control changes. 


static INotificationld const 
pageBackgroundColorld; 


Supported On: 

PM, Motif 
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Styles 

Use these members to set and query the various styles that are associated with a notebook. You 
can use these styles with the styles defined by the following nested classes: 

IWindow::Styles (Vol. II) 

IControl::Styles (Vol. II) 

The combination of styles you specify for the back pages (the recessed edges that give the 
notebook a three-dimensional effect) and the major tabs determines how the pages in the 
notebook look and behave when the user iterates through the notebook's pages. 

An object of this nested class is provided when you create a notebook. A customizable default is 
used if you do not specify any styles. Once the notebook object is created, you can use 
INotebook, IWindow, and IControl member functions to set or query the object's style. 

The declaration of the INotebook::Style nested class is generated by the 
INESTEDBITFLAGCLASSDEF2 macro. 


backPagesBottomLeft 

Draws the back pages of the notebook behind the bottom left corner of the notebook. 

static const Style Supported On: 

backPagesBottomLeft; PM. Motif 

backPagesBottomRight 

Draws the back pages of the notebook behind the bottom right comer of the 
notebook. This is the default. 


static const Style 
backPagesBottomRight; 


Supported On: 

PM. Motif 


backPagesT opLeft 

Draws the back pages of the notebook behind the top left corner of the notebook. 


static const Style Supported On: 

backPagesTopLeft; PM. Motif 

backPagesTopRight 

Draws the back pages of the notebook behind the top right corner of the notebook. 


static const Style 
backPagesTopRight; 


Supported On: 

PM. Motif 
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classDefaultStyle 

Specifies the original default style for this class, which is the combination of the 
following: 

squareTabs 

solidBinding 

statusTextLeft 

tabTextCenter 

backPagesBottomRight 

majorTabsRight 

IWindow::visible 

static const Style 
classDefaultStyle; 

majorTabsBottom 

Draws the major tabs of the notebook on the bottom of the notebook. 

static const Style Supported On: 

majorTabsBottom; PM, Motif 


Supported On: 

PM, Motif 


majorTabsLeft 

Draws the major tabs of the notebook on the left side of the notebook. 


static const Style 
majorTabsLeft; 


Supported On: 

PM, Motif 


majorTabsRight 

Draws the major tabs of the notebook on the right side of the notebook. This is the 
default. 


static const Style 
majorTabsRight; 


Supported On: 

PM, Motif 


majorTabsTop 

Draws the major tabs of the notebook on the top of the notebook. 


static const Style 
majorTabsTop; 


Supported On: 

PM, Motif 
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—Draws tabs with polygon comers. 

static const Style 
polygonTabs; 

—Draws tabs with rounded corners. 


static const Style 
roundedTabs; 

—Draws a solid binding. This is the default. 


static const Style 
solidBinding; 

_Draws a spiral binding. 


static const Style 
spiralBinding; 

—Draws tabs with square corners. This is the default. 

static const Style 
squareTabs; 


statusTextCenter 

Centers the text in the status line. 


static const Style 
statusTextCenter; 


statusTextLeft 

Left-justifies the text in the status line. This is the default. 


static const Style 
statusTextLeft; 


statusTextRight 

Right-justifies the text in the status line. 


static const Style 
statusTextRight; 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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tabTextCenter 

Centers the text in the tabs. This is the default. 


static const Style Supported On: 

tabTextCenter; PM, Motif 

„Left-justifies the text in the tabs. 


static const Style Supported On: 

tabTextLeft; PM. Motif 

_Right-justifies the text in the tabs. 


static const Style 
tabTextRight; 


Supported On: 

PM, Motif 


Inherited Public Data 


IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Nested Classes 

INotebook contains the following nested classes: 

INotebook::PageSettings (see page 1102) 
INotebook::Cursor (see page 1098) 
INotebook::Style (see page 1111) 


Orientation { 

backpagesBottomTabsRight, 
backpagesBottomTabsLeft, 
backpagesRightTabsTop, 
backpagesRightTabsBottom, 
}; 


backpagesTopTabsRight, 
backpagesTopTabsLeft, 
backpagesLeftTabsTop, 
backpagesLeftTabsBottom 


Use these enumerators to specify the orientation of the back pages’ corner in relation 
to the location of the major tabs: 

backpagesBottomT absRight 

Places back pages on the bottom-right comer and the major tabs on the right 
side of the notebook. 

backpagesTopTabsRight 

Places back pages on the top-right corner and the major tabs on the right side 
of the notebook. 

backpagesBottomT absLeft 

Places back pages on the bottom-left corner and the major tabs on the left side 
of the notebook. 

backpagesTopTabsLeft 

Places back pages on the top-left corner and the major tabs on the left side of 
the notebook. 

backpagesRightT absT op 

Places back pages on the top-right corner and the major tabs on the top of the 
notebook. 

backpagesLeftT absT op 

Places back pages on the top-left corner and the major tabs on the top of the 
notebook. 

backpagesRightT absBottom 

Places back pages on the bottom-right corner and the major tabs on the bottom 
of the notebook. 

backpagesLeftT absBottom 

Places back pages on the bottom-left corner and the major tabs on the bottom 
of the notebook. 
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TextAlignment 

TextAlignment { 
left, 
right, 
center 
}; 


Use these enumerators to specify the alignment for the text in the status line and in 
the tabs: 

left 

Left-justifies the text. 

right 

Right-justifies the text. 

center 

Centers the text. 


Binding { 
spiral, 
sol i d 
}; 


Use these enumerators to specify the binding for the notebook: 

spiral 

Draws a spiral binding for the notebook. 

solid 

Draws a solid binding for the notebook. 

TabShape { 
square, 
rounded, 
polygon 
}; 


Use these enumerators to specify the shape of the notebook’s tabs: 

square 

Draws the tabs with square corners. 

rounded 

Draws the tabs with rounded corners. 

polygon 

Draws the tabs with polygon corners. 
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INotebook::Cursor 


IBase 

IVBase 

INotebook:: Cursor 


_.None. 

—inotebk.hpp 


Member 

Page 

Member 

Page 

Constructor 

1098 

previous 

1100 

current 

1100 

setCurrent 

1100 

Cursor 

1098 

setToFirst 

1099 

first 

1100 

setToLast 

1099 

invalidate 

1099 

setToNext 

1099 

is Valid 

1099 

setToPrevious 

1099 

last 

1100 

'Cursor 

1099 

next 

1100 




The nested class INotebook::Cursor defines objects that you can use to iterate through 
the pages of a notebook. In the same way that you can use a cursor to iterate through 
the objects in a collection, you can use this cursor object to iterate through a 
notebook, one page at a time. 

An object of this class processes IPageHandle (p. 1121) objects, each of which can be 
thought of as a pointer to a specific page in the notebook. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

.You can only create objects of this nested class by specifying a notebook. Use the 
object to iterate through the pages of the notebook that you specified. 

Cursor( const INotebook& notebook); Supported On: 

PM, Motif 
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notebook Reference to the notebook object. 


Cursor 


virtual 
"Cursor(); 


Page Iteration 

Use these members to iterate through the pages of a notebook. 
_Flags this cursor as not valid. 


virtual void 
inval idate(); 

Queries whether the cursor points to a valid item, and returns true 


virtual Boolean 
isValid() const; 

-Sets the cursor to point to the first page of the notebook. 


virtual Boolean 
setToFirst(); 

-Sets the cursor to point to the last page of the notebook. 


virtual Boolean 
setToLast(); 

- Sets the cursor to point to the next page of the notebook. 


virtual Boolean 
setToNext(); 


setToPrevious 

Sets the cursor to point to the previous page of the notebook. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 

if it does. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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Page Retrieval 

Use these members to retrieve notebook pages. 

Returns an IPageHandle (p. 1121) object for the notebook page to which the cursor 
currently points. 


virtual IPageHandle Supported On: 

current() const; PM. Motif 

Points to the first page in the notebook and returns an IPageHandle (p. 1121) object 
that points to the first notebook page. 


virtual IPageHandle Supported On: 

fi rst(); PM. Motif 

Points to the last page in the notebook and returns an IPageHandle (p. 1121) object 
that points to the last notebook page. 


virtual IPageHandle Supported On: 

last(); PM. Motif 

Points to the next page in the notebook and returns an IPageHandle (p. 1121) object 
that points to the next notebook page. 


virtual IPageHandle Supported On: 

next(); PM. Motif 

.Points to the previous page in the notebook and returns an IPageHandle (p. 1121) 
object that points to the previous notebook page. 


virtual IPageHandle Supported On: 

previous (); PM. Motif 

... Sets the cursor to point to the specified notebook page, therefore making it the 
current page. 


voi d 

setCurrent( const IPageHandle& current); 


Supported On: 

PM. Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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INotebook::PageSettings 


IBase 

IVBase 

INotebook: :PageSettings 


_.None. 

—inotebk.hpp 


Member 

Page 

Constructor 

1103 

autoPageSize 

1107 

isAutoSize 

1103 

isMajorTab 

1106 

isMinorTab 

1106 

isStatusTextOn 

1105 

majorTab 

1108 

minorTab 

1108 

noAttribute 

1108 

PageSettings 

1103 


Member 

Page 

setStatusText 

1105 

setTabBitmap 

1106 

setTabText 

1106 

setUserData 

1103 

statusText 

1106 

statusTextOn 

1108 

tabBitmap 

1107 

tabText 

1107 

userData 

1103 

'PageSettings 

1105 


The nested class INotebook::PageSettings identifies information about a page in a 
notebook. You create objects of this nested class to define characteristics of pages 
when adding the pages to a notebook. You can use one object of this nested class to 
create multiple pages that have the same characteristics. 

You can also create an object of this nested class to reflect the current state of a page 
in a notebook. 

The INotebook::PageSettings object only identifies the characteristics of a page at one 
point in time, such as when you are adding the page to a notebook. The object is not 
updated when the actual page changes. Also, changes to the INotebook::PageSettings 
object are not reflected in the actual page after it is added to a notebook. 


Public Functions 
Application Data 

Use these members to query and set the application data associated with an 
INotebook::PageSettings object. 

1102 Open Class Library Reference 







INotebook: :PageSettings 


Note: Once an INotebook::PageSettings object has been used to insert a page into a notebook, 
using these members on the object has no effect on the application data within the actual 
notebook page; therefore, you should use the corresponding application data members 
located within INotebook. However, you can still use these members to update the 
application data associated with the INotebook::PageSettings object, and you can use the 
object to define a new notebook page. 

... Sets the application data into the page's reserved storage. Each page has a 4-byte 

reserved storage area. This area is available for information required by your 

application. 

virtual INotebook::PageSettings& Supported On: 

setUserData( unsigned long userData); PM, Motif 

userData Unsigned long value that represents the application data to be set into the 
page’s storage. 

-Returns the application data from the page's reserved storage. 

virtual unsigned long Supported On: 

userData() const; PM, Motif 


Automatic Sizing 

Use these members to determine if the page is automatically sized by the notebook. 

-.Queries whether the page is automatically sized by the notebook, and returns true if 
it is. 


Boolean 

isAutoSize() const; 


Supported On: 

PM, Motif 


Constructors 

You can construct and destruct objects of this class. 

_.You can create objects of this class by specifying various parameters. 

Q PageSettings( const I BitmapHandle& tabBitmap, Supported On: 

const char* statusText = 0, PM, Motif 

const Attribute& pageAttribute = noAttribute); 

tabBitmap Reference to the handle of the bitmap to use on the notebook page's tab. 

statusText Pointer to the text to use on the status line of the notebook page. 
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pageAttribute 

Reference to an INoteBook::PageSettings::Attribute object. The default is 
INotebook: :PageSettings::noAttribute. 

You can construct an object of this nested class by using the tab bitmap, status text, 
and one or more attributes. Use this constructor when you do not want to specify 
text for the tab. 

3 PageSettingsO; Supported On: 

PM, Motif 

You can create an object of this nested class by using this, the default constructor. 

The User Interface Class Library defines the default attribute to be 
INotebook::PageSettings::noAttribute, and all of the other page settings values are set 
to 0. 

0 PageSettings( const Attributes attribute); Supported On: 

PM, Motif 

attribute Reference to an INoteBook::PageSettings::Attribute object. 

You can create an object of this nested class by using one or more page attributes. 

All of the other page settings are set to 0. 

Q PageSettings( const char* tabText, Supported On: 

const char* statusText = 0, PM, Motif 

const Attribute& pageAttribute = noAttribute); 

tabText Pointer to the text to use on the notebook page's tab. 

statusText Pointer to the text to use on the status line of the notebook page. 

pageAttribute 

Reference to an INoteBook::PageSettings::Attribute object. The default is 
INotebook: :PageSettings::noAttribute. 

You can create an object of this nested class by using the tab text, status text, and 
one or more attributes. Use this constructor when you do not want to specify a 
bitmap for the tab. 

0 PageSettings ( Supported On: 

const INotebook:: PageSetti ngsS pageSettings); PM, Motif 
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pageSettings 

Reference to the page settings object to copy. 

Use this constructor to copy another INotebook::PageSettings object. 


PageSettings 


virtual 

'PageSettingsO; 


Supported On: 

PM, Motif 


Status Text 

Use these members to query and set the status text associated with an INotebook: :PageSettings 
object. 

Note: Once an INotebook::PageSettings object has been used to insert a page into a notebook, 
using these members on the object has no effect on the status text within the actual 
notebook page; therefore, you should use the corresponding status text members located 
within INotebook. However, you can still use these members to update the status text 
associated with the INotebook::PageSettings object, and you can use the object to define 
a new notebook page. 


isStatusTextOn 

Queries whether a status line is associated with the page, and returns true if one is. 


Boolean 

isStatusTextOn() const; 


Supported On: 

PM, Motif 


setStatusText 

Sets the text of the status line associated with this page. Calling this function adds 
the INotebook::PageSettings::statusTextOn (p. 1108) attribute to the settings object. 

Q virtual INotebook::PageSettings& Supported On: 

setStatusText( const IResourceId& resourceld); PM, Motif 

resourceld Reference to a resource identifier object that identifies the text to use on 
the status line of the notebook page. 


§ virtual INotebook::PageSettings& Supported On: 

setStatusText( const char* statusText); PM, Motif 

statusText Pointer to the text to use on the status line of the notebook page. 
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Returns the text of the status line associated with this page. 


virtual IString 
statusText() const; 


Supported On: 

PM. Motif 


Tabs 

Use these members to query and set the tab's text or bitmap associated with an 
INotebook::PageSettings object. 

Note: Once an INotebook::PageSettings object has been used to insert a page into a notebook, 
using these members on the object has no effect on the notebook page’s tab; therefore, 
you should use the corresponding tab members located within INotebook. However, you 
can still use these members to update the tab text or bitmap associated with the 
INotebook::PageSettings object, and you can use the object to define a new notebook 
page. 

..Queries whether a major tab is associated with the page, and returns true if one is. 

Bool ean Supported On: 

isMajorTab() const; PM, Motif 

..Queries whether a minor tab is associated with the page, and returns true if one is. 

Bool ean Supported On: 

isMinorTab() const; PM, Motif 

setTabBitmap 

Sets the bitmap of the tab associated with this page. 

[] virtual INotebook:: PageSettings& Supported On: 

setTabBitmap( const IResourceId& resourceld); PM, Motif 

resourceld Reference to a resource identifier object that identifies the bitmap to use 
on the notebook page’s tab. 

2 virtual INotebook:: PageSettings& Supported On: 

setTabBitmap( const IBitmapHandle& bitmap); PM, Motif 

bitmap Reference to the handle of the bitmap to use on the notebook page’s tab. 

. Sets the text of the tab associated with this page. 
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Q virtual INotebook::PageSettings& Supported On: 

setTabText( const IResourceId& resourceld); PM, Motif 

resourceld Reference to a resource identifier object that identifies the text to use on 
the notebook page’s tab. 


@ virtual INotebook::PageSettings& Supported On: 

setTabText( const char* tabText); PM, Motif 

tabText Pointer to the text to use on the notebook page’s tab. 


.Returns the bitmap of the tab associated with this page. 


virtual IBitmapHandl e Supported On: 

tabBitmapO const; PM, Motif 

Returns the text of the tab associated with this page. 


virtual IString 
tabText() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 
Attributes 

These members define the various attributes that are associated with a notebook page. 


autoPageSize 

Specifies the positioning and sizing of the notebook page. When you create a page 
using this attribute, the system resizes the window associated with the page so that it 
fills in the page area. 
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static const Attribute Supported On: 

autoPageSize; PM, Motif 

.-Specifies that the page is associated with a major tab. 


static const Attribute Supported On: 

majorTab; PM, Motif 

...Specifies that the page is associated with a minor tab. 


static const Attribute Supported On: 

minorTab; PM, Motif 

—Specifies that no attribute applies to the notebook page. 


static const Attribute Supported On: 

noAttribute; PM, Motif 

— Specifies that the page has a status line. You cannot assign status text to a page 
without a status line. 


static const Attribute Supported On: 


statusTextOn; 


PM, Motif 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 



Nested Classes 

INotebook::PageSettings contains the following nested classes: 
INotebook::PageSettings::Attribute (see page 1109) 


1108 
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INotebook::PageSettings::Attribute 


IBase 

IBitFlag 

INotebook: :PageSettings:: Attribute 


_.None. 

_inotebk.hpp 

The nested class INotebook::PageSettings::Attribute provides a set of valid notebook 
page attributes for the member functions of the nested class INotebook::PageSettings 

(p. 1102). 

An object of this class is provided when the notebook page is created. 

The declaration of the INotebook::PageSettings::Attribute nested class is generated by 
the INESTEDBITFLAGCLASSDEFO macro. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 
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INotebook: :PageSettings: :Attribute 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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INotebook::Style 


IBase 

IBitFlag 

INotebook::Style 


_.None. 

_inotebk.hpp 

The nested class INotebook:: Style provides static members that define the set of valid 
notebook styles for the class INotebook (p. 1066). 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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INotebookDrawItem Event 


IBase 

IVBase 

IEvent 

IControlEvent 

IDrawItemEvent 

INotebookDrawItemEvent 


_.None. 

_i n hdicv't. hpp 


Member 

Page 

Member 

Page 

Constructor 

1112 

page 

1113 

itemld 

1113 

'INotebookDrawItemEvent 

1113 


The INotebookDrawItemEvent class provides event information for drawing a tab on 
a notebook page. This draw-item event is generated only if a notebook page has a 
tab that does not have text or a bitmap attached to it. 


Public Functions 
Constructors 

Use these members to create objects of this class. 


INotebookDrawItemEvent 

You can only construct an object of this class from a reference to an object of the 
IEvent (Vol. II) class. 

INotebookDrawItemEvent( IEvent& event); Supported On: 

PM, Motif 

event Reference to an event object. 


1112 
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INotebookDrawItemEvent 


virtual 

'INotebookDrawItemEvent() ; 


Supported On: 

PM, Motif 


Page Information 

Use these members to obtain information about the notebook page. 

Returns an identifier for the page whose tab is to be drawn. 

INotebookDrawItemEvent::page (p. 1113) uses this value to return an IPageHandle (p. 

1121). 


virtual unsigned long Supported On: 

itemld() const; PM. Motif 

Returns a handle to the page whose tab is to be drawn. 


virtual IPageHandle 
page() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IDrawItemEvent 

itemld 

itemPresSpaceHandle 

itemRect 


IControIEvent 

controlld 




IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 
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IN otebookDrawItemE vent 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDrawItemEvent 

ownerltemData 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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INotebookNotifyHandler 


IBase 

IVBase 

IHandler 

IWindowNotifyHandler 

INotebookNotifyHandler 


_.None. 

_ inotebnh.hpp 


Member Page 

Constructor 1115 

dispatchHandlerEvent 1116 

"INotebookNotifyHandler 1116 


Instances of the INotebookNotifyHandler class process events for all classes of 
notebooks. 


This class is designed to handle events that require the notebook class to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


INotebookNotifyHandler 

Default constructor. 


INotebookNotifyHandler(); 


Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


INotebookDrawItemEvent 1115 







INotebookNotifyHandler 


"INotebookNotifyHandler 


virtual 

'INotebookNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event-processing members evaluate an event to determine if it is appropriate for this handler 
object to process. 

dispatchHandlerEvent 

If any of the following events are received, the notebook observers are notified: 

• backgroundPageColor event 

• backgroundMajorColor event 

• backgroundMinorColor event 

• foregroundMajorColor event 

• foregroundMinorColor event 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& anEvent); PM, Motif 
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INotebookNotifyHandler 


Inherited Protected Functions 



Inherited Protected Data 
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IPageEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

IPageEvent 


IPageHelpEvent 

IPageRemoveEvent 

IPageSelectEvent 


_ ipageevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

1118 

pageHandle 

1119 

notebook 

1119 

'IPageEvent 

1119 


The IPageEvent class represents a notification for a page-related notebook event. A 
notebook page handler creates an object of this class when a notebook page is 
resized. This class is also the base class for other page-related events. 

Note: Page events are first dispatched to the notebook and then to the owner 
window of the notebook. 


Public Functions 
Constructors 

Although you can construct objects of this class, typically IPageHandler::dispatchHandlerEvent 
(p. 1125) constructs objects of this class from an object of the class IEvent (Vol. II) or 
IControlEvent (Vol. II). You can also destruct objects of this class. 


IPageEvent 


| IPageEvent( const IEvent& event); 


Supported On: 

PM, Motif 
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IPageEvent 


event Reference to an event object. 

Use this version of the constructor to create a page event object from an event object. 

§ IPageEvent( const IControlEvent& control Event); Supported On: 

PM. Motif 

controlEvent 

Reference to a control event object. 

Use this version of the constructor to create a page event object from a control event 
object. 

g IPageEvent( const IPageEvent& pageEvent); 

pageEvent Reference to a page event object 

Use this version of the constructor, the copy constructor, to create a page event object 
from another page event object. 

IPageEvent 


Supported On: 

PM, Motif 


virtual 

"IPageEventO; 


Supported On: 

PM, Motif 


Page Information 

Use these members to obtain information about the page that is the subject of the notification 
event and the notebook. 

_ Returns a pointer to the notebook object that the page belongs to. This page is the 
target of the notification event. 


virtual INotebook* Supported On: 

notebook() const; PM, Motif 

_Returns the notebook page handle that is the subject of the notification event. 


virtual IPageHandle 
pageHandle() const; 


Supported On: 

PM, Motif 
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Inherited Public Functions 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IPageHandle 


IBase 

IHandle 

IPageHandle 


_.None. 

_inotebk.hpp 

Member Page 

Constructor 1121 

operator Value 1122 


The IPageHandle class represents a page in a notebook. The User Interface Class 
Library only enables notebooks to construct objects of this class. A notebook returns 
an IPageHandle when the following occurs: 

• A page is added to the notebook. The IPageHandle represents the new page. 

• A page is queried, such as a call to INotebook::firstPage (p. 1078). 

You can use an object of this class to identify a page, just as you can identify a page 
with an INotebook::Cursor (p. 1098) object. 


Public Functions 
Constructors 

You can create objects of this class from a page identifier, which defaults to 0. 


IPageHandle 


IPageHandle( Value pageld = 0); Supported On: 

PM, Motif 

pageld IHandle::Value value that represents the page identifier (ID). 
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Page Handle 

Use this operator to return the page handle value. 
_ Returns the page handle value. 

operator Value() const; 

Inherited Public Functions 

IHandle 

asDebuglnfo asString 

IBase 

asDebuglnfo messageFile 

asString messageText 

Inherited Protected Data 

IHandle 

handle 

IBase 

recoverable unrecoverable 
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Supported On: 

PM. Motif 


asUnsigned 

setMessageFile 

version 
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IPageHandler 


IBase 

IVBase 

IHandler 

IPageHandler 


_.None. 

_ ipagehdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

1124 

remove 

1126 

dispatchHandlerEvent 

1125 

resize 

1126 

drawTab 

1125 

select 

1126 

help 

1125 

'IPageHandler 

1124 


The IPageHandler class handles the processing of page change events for the 
INotebook (p. 1066) class. These events result from a user interacting with a 
notebook page. 

You can create a handler derived from IPageHandler and attach it to a notebook or to 
the notebook’s owner window. You attach it by calling IHandler::handleEventsFor 
(Vol. II) to identify the notebook or owner window to the page handler. 

This class dispatches the following events: 

Drawing a tab 

INotebookDrawItemEvent (p. 1112) 

Requesting help for a page 

IPageHelpEvent (p. 1127) 

Removing a page 

IPageRemoveEvent (p. 1130) 

Resizing a page 

IPageEvent (p. 1118) 

Selecting a page 

IPageSelectEvent (p. 1133) 
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When the page handler receives one of these events, it creates a corresponding event 
object and dispatches that object to the appropriate IPageHandler virtual function. 

You can override these virtual functions to supply customized processing of a page 
event. 

The return value from the virtual functions specifies whether the page event is passed 
on for additional processing, as follows: 

true The page event requires no additional processing. Do not pass it to another 
handler. 

false Pass the page event to the next handler for additional processing, as follows: 

• If there is another handler for the notebook, pass the page event to the 
next handler. 

• If this is the last handler for the notebook, call IWindow::dispatch (Vol. 
II) to dispatch the page event to the notebook’s owner window. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (Vol. II) to process the page event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

_.You can only construct objects of this class using this, the default constructor, 
which does not accept any parameters. 

IPageHandler(); Supported On: 

PM. Motif 


"IPageHandler 


virtual 

"TPageHandlerO ; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 
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IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event-dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process. If it is, this function calls the IPageHandler virtual function used to process 
the event. 

dispatchHandlerEvent 

If a page event is received, calls the appropriate IPageHandler virtual function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM. Motif 

event Reference to an event object. 


Event Processing 

Event-processing members override these functions in a derived class to process the various 
notebook page-related events. Use the overridden function to supply the customized processing 
of a page-related event. 

„It is implemented by derived classes. Draws the notebook page tab. 

virtual Boolean Supported On: 

drawTab( INotebookDrawItemEvent& event); PM 

event Reference to a notebook event object that provides tab drawing 
information. 

.It is implemented by derived classes. Processes a notification that help has been 
requested for a notebook page. 
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virtual Boolean Supported On: 

help( IPageHelpEvent& event); PM, Motif Ignored 

event Reference to a page help event object. 

1" ~ j You can set up help for individual notebook pages by setting up the help table and 
IHelpWindow object for each page in exactly the same way as for any other window 
object. 

.. It is implemented by derived classes. Processes a page remove notification. 

virtual Boolean Supported On: 

remove( IPageRemoveEvent& event); PM, Motif Ignored 

event Reference to a page remove event object. 

..It is implemented by derived classes. Processes a notification that the page size 
changed. 


virtual Boolean Supported On: 

resize( IPageEvent& event); PM, Motif Ignored 

event Reference to a page event object. 

..It is implemented by derived classes. Processes the notification that a new page is at 
the top of the notebook. 


virtual Boolean Supported On: 

select( IPageSelectEvent& event); PM. Motif 

event Reference to a page select event object. 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IPageHelpEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

IPageEvent 

IPageHelpEvent 


_.None. 


_ ipageevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

1127 

pageHandle 

1129 

helpWindow 

1128 

“IPageHelpEvent 

1128 

notebook 

1128 




The IPageHelpEvent class represents a notification that help has been requested for a 
notebook page. A notebook page handler creates and uses an object of this class. 

Note: This event is first dispatched to the notebook and then to the owner window 
of the notebook. 

| Motif The AIX release of the User Interface Class Library does not support this class. 


Public Functions 
Constructors 

Although you can construct objects of this class, typically IPageHandler::dispatchHandlerEvent 
(p. 1125) constructs objects of this class from an object of the class IEvent (Vol. II), 
IControlEvent (Vol. II), or IPageEvent (p. 1118). You can also destruct objects of this class. 


IPageHelpEvent 

Q IPageHel pEvent( const IEvent& event); Supported On: 

PM, Motif Ignored 
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IPageHelpEvent 


event Reference to an event object. 

Use this version of the constructor to create a page help event object from an event 
object. 

g IPageHel pEvent( const IControlEvent& control Event); Supported On: 

PM, Motif Ignored 

controlEvent 

Reference to a control event object. 

Use this version of the constructor to create a page help event object from a control 
event object. 

2 IPageHel pEvent( const IPageEvent& pageEvent); Supported On: 

PM, Motif Ignored 

pageEvent Reference to a page event object. 

Use this version of the constructor to create a page help event object from a page 
event object. 

"IPageHelpEvent 

virtual Supported On: 

*IPageHelpEvent(); PM, Motif Ignored 


Help Information 

Use these members to obtain help information. 

_ Returns the help window you can use to display help for the notebook page. 


IHelpWindow* 
helpWindow() const; 


Supported On: 

PM, Motif Ignored 


Page Information 

Use these members to obtain information about the page that is the target of the help request and 
the notebook. 

-Returns a pointer to the notebook object that the page belongs to. 


virtual INotebook* 
notebook() const; 


Supported On: 

PM, Motif Ignored 
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_Returns the handle of the notebook page for which help has been requested. 


virtual IPageHandle 
pageHandle() const; 


Supported On: 

PM. Motif Ignored 


Inherited Public Functions 


IPageEvent 

notebook 

pageHandle 



IControIEvent 

controlld 




IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IPageRemoveEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

IPageEvent 

IPageRemoveEvent 


_.None. 

... ipageevt.hpp 

Member 

Constructor 
notebook 
pageWindow 

The IPageRemoveEvent class represents a notification of the removal of a notebook 
page. A notebook page handler creates and uses an object of this class. 

This event provides functions to return the application page window and bitmap. The 
application must delete the window and bitmap, if they exist. 

Note: This event is first dispatched to the notebook and then to the owner window 
of the notebook. 

1 ~ The AIX release of the User Interface Class Library does not support this class. 


Page 

Member 

Page 

1131 

tabBitmap 

1132 

1131 

'IPageRemoveEvent 

1131 

1131 





Public Functions 
Constructors 

Although you can construct objects of this class, typically IPageHandler::dispatchHandlerEvent 
(p. 1125) constructs objects of this class from an object of the class IEvent (Vol. II), 
IControlEvent (Vol. II), or IPageEvent (p. 1118). You can also destruct objects of this class. 
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IPageRemoveEvent 


IPageRemoveEvent 

Q IPageRemoveEvent( const IEvent& event); Supported On: 

PM, Motif Ignored 

event Reference to an event object. 

Use this version of the constructor to create a page remove event object from an 
event object. 

§ IPageRemoveEvent ( const IControlEvent& control Event); Supported On: 

PM, Motif Ignored 

controlEvent 

Reference to a control event object. 

Use this version of the constructor to create a page remove event object from a 
control event object. 

g IPageRemoveEvent( const IPageEvent& pageEvent); Supported On: 

PM, Motif Ignored 

pageEvent Reference to a page event object. 

Use this version of the constructor to create a page remove event object from a page 
event object. 

"IPageRemoveEvent 

virtual Supported On: 

"IPageRemoveEventO ; PM. Motif Ignored 


Page Information 

Use these members to obtain information about the deleted page and the notebook. 
_ Returns a pointer to the notebook object that the page belongs to. 


virtual INotebook* Supported On: 

notebookO const; PM, Motif Ignored 

—Returns the window or control associated with the page. 


IWindow* 

pageWindow() const; 


Supported On: 

PM, Motif Ignored 
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.Returns the handle of the bitmap used by the tab associated with the page. 


IBi tmapHandle 
tabBitmap() const; 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


IPageEvent 

notebook 

pageHandle 



IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



1132 Open Class Library Reference 







IPageSelectEvent 



IPageSelectEvent 


IBase 

IVBase 

IEvent 

IControlEvent 

IPageEvent 

IPageSelectEvent 


_.None. 

_ ipageevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

1133 

previousSelectedPageHandle 

1135 

notebook 

1134 

'IPageSelectEvent 

1134 

pageHandle 

1134 




The IPageSelectEvent class represents a notification that a page has been selected in a 
notebook. A notebook page handler creates and uses an object of this class. 

Note: This event is first dispatched to the notebook and then to the owner window 
of the notebook. 


Public Functions 
Constructors 

Although you can create objects of this class, typically IPageHandler::dispatchHandlerEvent (p. 
1125) creates objects of this class from an object of the class IEvent (Vol. II), IControlEvent 
(Vol. II), or IPageEvent (p. 1118). 


IPageSelectEvent 

Q IPageSelectEvent( const IEvent& event); Supported On: 

PM, Motif 
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event Reference to an event object. 

Use this version of the constructor to create a page select event object from an event 
object. 


2 IPageSelectEvent( const IControlEvent& control Event); 


controlEvent 

Reference to a control event object. 


Supported On: 

PM. Motif 


Use this version of the constructor to create a page select event object from a control 
event object. 


2 IPageSelectEvent( const IPageEvent& pageEvent) ; Supported On: 

PM. Motif 

pageEvent Reference to a page event object. 

Use this version of the constructor to create a page select event object from a page 
event object. 

IPageSelectEvent 


virtual 

"IPageSelectEventO; 


Supported On: 

PM. Motif 


Page Information 

Use these functions to obtain information about the selected page, previously selected page, and 
the notebook. 

-Returns a pointer to the notebook object that the page belongs to. 


virtual INotebook* Supported On: 

notebook() const; PM. Motif 

_Returns the handle of the selected notebook page. 


virtual IPageHandle 
pageHandle() const; 


Supported On: 

PM. Motif 
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previousSelectedPageHandle 

Returns the handle of the previously selected notebook page. 


IPageHandle 

previousSelectedPageHandle() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IPageEvent 

notebook 

pageHandle 



IControlEvent 

controlld 




IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IRegionHandle 


IBase 

IHandle 

IRegionHandle 


_.None. 

—ihandle.hpp 

Member Page 

Constructor 1136 


Objects of the IRegionHandle class access a window's update region. 

IPM IRegionHandle is an alias for the OS/2 Programmer's Toolkit HRGN typedef. 
IMotifl The AIX release does not support this class. 


Public Functions 
Constructors 

You can construct objects of this class. 


IRegionHandle 

You can construct objects of this class from a region handle (a value of type 
IHandle::Value), which defaults to 0. 


IRegionHandle( Value hregion = 0); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 
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IRegionHandle 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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ISetCanvas 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ICanvas 

ISetCanvas 


IToolBar 

IToolBarContainer 


—isetcv.hpp 


Member 

Page 

Member 

Page 

Constructor 

1139 

packTight 

1150 

alignment 

1142 

packType 

1142 

border 

1148 

pad 

1142 

bottomAlign 

1148 

position 

1145 

centerAlign 

1148 

rightAlign 

1150 

centerV ertical Align 

1148 

setAlignment 

1143 

classDefaultStyle 

1148 

setDeckCount 

1141 

con vertT oGUISty le 

1144 

setDeckOrientation 

1141 

deckCount 

1140 

setDefaultStyle 

1144 

deckOrientation 

1141 

setGroupPad 

1143 

deckOrientationld 

1147 

setLayoutDistorted 

1142 

decksByGroup 

1149 

setMargin 

1143 

defaultStyle 

1144 

setPackType 

1143 

expandForText 

1147 

setPad 

1143 

groupPad 

1142 

setText 

1144 

horizontalDecks 

1149 

size 

1145 

layout 

1146 

text 

1145 

leftAlign 

1149 

textld 

1147 

margin 

1142 

topAlign 

1150 

moveSizeTo 

1145 

topHandle 

1141 

packEven 

1149 

verticalDecks 

1150 

packExpanded 

1150 

'ISetCanvas 

1140 


Objects of the ISetCanvas class are windows that organize their child windows in row 
or column decks. 
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Deck is the direction-independent term for a line of child windows in a set canvas 
window. A horizontal deck is equivalent to a row and a vertical deck is equivalent to 
a column. An ISetCanvas object can hold more than one deck of child windows, but 
the decks must be either all horizontal or all vertical. 

This class arranges fixed-size child windows of similar size, such as a row of push 
buttons or a group of radio buttons. You can divide these child windows evenly 
among multiple decks by number rather than by size. ISetCanvas also sizes and 
positions its child windows based on their minimum sizes instead of the size of the 
canvas. ISetCanvas uses IWindow::minimumSize (Vol. II) and 
IWindow::calcMinimumSize (Vol. II) to size the windows. 

This class provides you a number of alignment and packing option controls over how 
differently-sized child windows can be positioned. 

Note: To have a group box appear around the contents of a set canvas, use the 
function ISetCanvas::setText (p. 1144), in place of creating an IGroupBox (Vol. II) 
object. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign ISetCanvas 
objects because both the copy constructor and assignment operator are private functions. 


ISetCanvas 


ISetCanvas( unsigned long windowldentifier, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

id Window identifier of the canvas you construct. 

Note: For OS/2, this value should be limited to the range 0 through 
65535. 

It is recommended that you: 

• Give unique identifiers to all windows in the same frame window. In 
the same window means that the frame window is the first frame in 
their parent window chain. 

• Give the client window a window ID of FID_CLIENT (0x8008). 

• Do not use the other FID_xxx values. 


Supported On: 

PM, Motif 
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parent The parent window of the canvas you construct. You must specify a 

parent window. This constructor throws an IlnvalidParameter exception 
if you pass an IWindow* of 0. 

The parent window is primarily used for visible relationships. 

owner Owner window of the canvas you construct. 

Note: In OS/2, the owner window is primarily used for routing 

notification events and unprocessed messages. OS/2 also uses the 
owner window chain to inherit colors. 

In Motif, the owner window is only used for routing unprocessed 
messages. There is no concept of an owner in Motif. 

initial (Optional) The initial position and size of the canvas you construct. The 
default constructor is IRectangle (Vol. I). The initial position is the 
lower-left corner of the canvas relative to the lower-left corner of the 
parent window. 


style (Optional) Use the styles provided by IMultiCellCanvas (p. 1063) Styles 

to specify the control's styles. 


Exceptions 


IlnvalidParameter 

style contains an invalid combination of styles, style cannot contain more 
than one deck orientation style (ISetCanvas::horizontalDecks and 

ISetCanvas: :verticalDecks), more than one pack style 
(ISetCanvas::packTight, ISetCanvas: :packEven, and 

ISetCanvas: :packExpanded), more than one horizontal alignment style 
(ISetCanvas: deft Align, ISetCanvas:: center Align, and 

ISetCanvas: :rightAlign), or more than one vertical alignment style 
(ISetCanvas: :topAlign, ISetCanvas: xenterVerticalAlign, and 

ISetCanvas:: bottom Align). 


ISetCanvas 


virtual 

"ISetCanvas(); 


Supported On: 

PM, Motif 


Decks 

Use these members to set and query whether child windows should be laid out horizontally in 
rows or vertically in columns. 

-Returns the maximum number of decks used by the canvas. If your ISetCanvas has 
a vertical orientation, this function determines the maximum number of columns of 
controls the canvas has. If your set canvas has a horizontal orientation, this function 
determines the maximum number rows of controls the canvas has. 
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unsigned long 
deckCount() const; 


Supported On: 

PM, Motif 


deckOrientation 

Returns an enumerator for deck direction. The returned value is an enumerator 
provided by DeckOrientation (p. 1151). 


DeckOrientation 
deckOrientation() const; 


Supported On: 

PM, Motif 


setDeckCount 

Sets the maximum number of decks used by the canvas. This function has no effect 
if the decksByGroup (p. 1149) style is being used. 


virtual ISetCanvas& Supported On: 

setDeckCount( unsigned long decks); PM, Motif 

setDeckOrientation 

Sets the direction of the decks. 


virtual ISetCanvas& Supported On: 

setDeckOri entati on ( DeckOrientation value); PM, Motif 

value Use the enumeration DeckOrientation (p. 1151) to specify the direction. 


Exceptions 

IlnvalidParameter You specified an uninitialized ISetCanvas::DeckOrientation value. 


Event Handling Implementation 

Event-handling implementation members perform processing needed to allow event handlers to 
properly receive and route events. 

_ Returns the top window system control for this compound control. 


virtual IWindowHandle 
topHandle() const; 


Supported On: 

Motif 


Layout Support 

Layout members determine how this class sizes and positions its child windows or how this 
window will be laid out on another canvas. 
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setLayoutDistorted 

Treats the following as changing the layout of its child windows: 

• A minimum size change for a child window 

• A font change (if the set canvas has text assigned) 

• An added child window 

• A removed child window 


virtual ISetCanvas& 

setLayoutDistorted( unsigned long layoutAttributesOn, 
unsigned long 1 ayoutAttributesOff); 


Supported On: 

PM, Motif 


Spacing of Child Windows 

Use these members to specify the spacing added around and between child windows. 

_ Returns the enumerator for deck alignment. The returned value is an enumerator 
provided by Alignment (p. 1153). 


A1 ignment Supported On: 

alignmentO const; PM. Motif 

..Returns the pad width or height, which is the space before a child window in a deck 
with a style of IControl::group. 


unsigned long Supported On: 

groupPadQ const; PM. Motif 

Returns the margin width and height, which is the space between the edge of the 
canvas and the outermost child windows. 


IS i z e Supported On: 

margin() const; PM. Motif 

.Returns an enumerator for child window spacing in decks. The returned value is an 
enumerator provided by PackType (p. 1153). 


PackType Supported On: 

packTypeQ const; PM. Motif 

Returns the pad width and height, which is the space between child windows in a 
deck and between multiple decks. 


ISize 

pad() const; 


Supported On: 

PM, Motif 
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_Sets how child windows are aligned in decks. 

Note: If the canvas uses a pack type of expanded, this function has no effect. 


virtual ISetCanvas& Supported On: 

setAl ignment( Alignment value); PM, Motif 

value Use the enumeration Alignment (p. 1153) to specify the child window 
alignment. 


Exceptions 

IlnvalidParameter You specified an uninitialized ISetCanvas::Alignment value. 


_Sets the pad width or height to use for controls with a style of IControl::group. The 
default value is zero. 


virtual ISetCanvas& Supported On: 

setGroupPad( unsigned long groupPad); PM, Motif 

...Sets the margin width and height, which is the space between the edge of the canvas 
and the outermost child windows. 


virtual ISetCanvas& Supported On: 

setMargin( const ISize& margin); PM, Motif 

_Sets how child windows are spaced in decks. 


virtual ISetCanvas& Supported On: 

setPackType( PackType value); PM, Motif 

value Use the enumeration PackType (p. 1153) to specify the spacing. 


Exceptions 

IlnvalidParameter You specified an uninitialized ISetCanvas::PackType value. 


...Sets the pad width and height, which is the space between child windows in a deck 
and between multiple decks. 


virtual ISetCanvas& 

setPad( const ISize& pad); 


Supported On: 

PM, Motif 
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Styles 

Use these style members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

_ Returns the default style. The default style is classDefaultStyle (p. 1148) unless you 
have changed the style using setDefaultStyle (p. 1144). 

static Style Supported On: 

defaul tStyl e(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent set canvases. 

static void Supported On: 

setDefaultStyle( const Style& style); PM, Motif 

style A combination of ISetCanvas::Style (p. 1147), ICanvas::Style (p. 34), and 

IWindow::Style (Vol. II) objects. 


Text 

Use these members to add a group box around the set canvas, or remove it and to query the text 
of the group box. 

Draws a group box with the specified text around the canvas. If necessary, the 
canvas is expanded to fill the width of the group box. 

[j virtual ISetCanvas& Supported On: 

setText( const char* text); PM, Motif 
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text The new group-box text. If you specify a null pointer or a zero-length 

string, an existing group box is removed. 

| Motif This function has no effect, if the set canvas was constructed without the border 

style. 

virtual ISetCanvas& Supported On: 

setText( const IResourceId& text); PM, Motif 

text The identifier of the string table resource for new group-box text. If you 

specify a zero-length string, an existing group box is removed. 

This function has no effect, if the set canvas was constructed without the border 
style. 

Returns the text of the group box. If the canvas has no surrounding group box, an 
empty IString (Vol. I) is returned. 

virtual IString 
text() const; 

Window Positioning 

Use these members to set and query the size and position of windows. 

_ Changes the position and size of the window. 

virtual ISetCanvas& 

moveSizeTo( const IRectangle& aRectangle); 

Returns the position of the window. 

virtual IPoint 
position() const; 

Returns the size of the window 


virtual ISize 
size() const; 


Inherited Public Functions 
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Motif 


Supported On: 

Motif 


Supported On: 

PM, Motif 




ISetCanvas 


ICanvas 

backgroundColor 

defaultStyle 

origDefaultButtonHandle 

convertToGUIStyle 

isTabStop 

setDefaultStyle 

defaultPushButton 

matchForMnemonic 

setLayoutDistorted 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Layout Support 

Layout members determine how this class sizes and positions its child windows or how this 
window will be laid out on another canvas. 

.Positions and sizes child windows. 


virtual ISetCanvas& 
layout(); 


Supported On: 

PM. Motif 


Text 

Use these members to add a group box around the set canvas, or remove it and to query the text 
of the group box. 
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expandForText 

Determines how much larger the canvas must be to include a group box with text. 


virtual ISetCanvas& 
expandForText(); 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The call to determine the size required to display the text of the set canvas 

failed. 


Inherited Protected Functions 


ICanvas 

areChildrenReversed 

layout 

registerCallbacks 

calcMinimumSize 

layoutSize 

setLay outSize 

fixupChildren 

passEventT oOwner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 

Notification Members 

ISetCanvas provides notifications that allow observers to process changes to the window. 

deckOrientationld 

Notification identifier provided to observers when the deck orientation of the set 
canvas changes. ISetCanvas provides the new deck orientation value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is one of the predefined DeckOrientation enumeration values. 

static INotificationld const Supported On: 

deckOrientationld; PM, Motif 

...Notification identifier provided to observers when the text of the set canvas changes. 

static INotificationld const Supported On: 

text Id; PM, Motif 
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Styles 


Use these style members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 

Draws a border around the set canvas. If you call the function setText (p. 1144), the 
text you specify will be placed in the border. 


static const Style 
border; 


Supported On: 

PM, Motif 


- Aligns child windows at the bottom edge of a horizontal deck or the bottom edge of 
a row between evenly packed vertical decks. 

Note: If you use this style with both packTight and verticalDecks, it is ignored. If 
you use this style with packExpanded, it is ignored. You cannot specify this 
style with topAlign or centerVerticalAlign. 


static const Style 
bottomAlign; 


Supported On: 

PM, Motif 


-Centers child windows horizontally within a vertical deck or within a column 
between evenly packed horizontal decks. 

Note: If you use this style with both packTight and horizontalDecks, it is ignored. 
If you use this style with packExpanded, it is ignored. You cannot specify 
this style with leftAlign or rightAlign. 


static const Style 
centerAlign; 


Supported On: 

PM, Motif 


centerVerticalAlign 

Centers child windows vertically within a horizontal deck or within a row between 
evenly packed vertical decks. 

Note: If you use this style with both packTight and verticalDecks, it is ignored. If 
you use this style with packExpanded, it is ignored. You cannot specify this 
style with topAlign or bottonrAlign. 


static const Style 
centerVerticalAl ign; 


Supported On: 

PM, Motif 


classDefaultStyle 
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Specifies the original default style for this class, which is ISetCanvas::horizontalDecks 
I ISetCanvas::packTight I ISetCanvas::leftAlign I ISetCanvas::topAlign I 
IWindow:: visible. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM, Motif 


decksByGroup 

Causes the number of decks in the set canvas to be determined by the number of 
child windows with the group style (IWindow::isGroup returns true). Each child 
window with the group style starts a new deck. If you specify this style, calls to 
setDeckCount are ignored. 

static const Style Supported On: 

decksByGroup; Motif 


horizontalDecks 

Organizes child windows in rows. Multiple rows are arranged from top to bottom. 
Note: You cannot specify this style with verticalDecks. 

static const Style Supported On: 

hori zontal Decks; PM, Motif 

..Aligns child windows at the left edge of a vertical deck or the left edge of a column 
between evenly packed horizontal decks. 

Note: If you use this style with both packTight and horizontalDecks, it is ignored. 

If you use this style with packExpanded, it is ignored. You cannot specify 
this style with rightAlign or centerAlign. 

static const Style Supported On: 

left Align; PM, Motif 

_ Sizes child windows to their minimum size and spaces them such that corresponding 
windows in each deck are aligned. This gives the child windows the appearance of 
being arranged in both rows and columns. As a result, child windows within a deck 
can be separated by more than the pad amount. 

Note: If the set canvas has only one deck, this style has no effect. You cannot 
specify this style with packTight or packExpanded. 


static const Style 
packEven; 


Supported On: 

PM, Motif 
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packExpanded 

Sizes child windows in a way similar to that of packEven, except the child windows 
are enlarged rather than spaced by more than the pad amount. All smaller child 
windows are enlarged to the same size as the largest child window. 

Note: You cannot specify this style with packTight or packEven. 

static const Style Supported On: 

packExpanded; PM. Motif 

_ Sizes child windows to their minimum size and separates them within a deck by the 
pad amount only. 

Note: You cannot specify this style with packEven or packExpanded. 


static const Style Supported On: 

packTight; PM. Motif 

.Aligns child windows at the right edge of a vertical deck or the right edge of a 

column between evenly packed horizontal decks. 

Note: If you use this style with both packTight and horizontalDecks, it is ignored. 

If you use this style with packExpanded, it is ignored. You cannot specify 
this style with leftAlign or centerAlign. 


static const Style Supported On: 

rightAl ign; PM. Motif 

.Aligns child windows at the top edge of a horizontal deck or a row between evenly 

packed vertical decks. 

Note: If you use this style with both packTight and verticalDecks, it is ignored. If 
you use this style with packExpanded, it is ignored. You cannot specify this 
style with bottomAlign or centerVerticalAlign. 


static const Style Supported On: 

topAlign; PM, Motif 

—Organizes child windows in columns. Multiple columns are arranged from left to 
right. 

Note: You cannot specify this style with horizontalDecks. 


static const Style 
verticalDecks; 


Supported On: 

PM, Motif 
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Inherited Public Data 


ICanvas 

classDefaultStyle 




IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandtd 

deletetd 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

ISetCanvas contains the following nested classes: 
ISetCanvas::Style (see page 1155) 


DeckOrientation 


DeckOrientation { 
horizontal, 
vertical 
}; 


Use the following enumerators to specify the direction in which to orient the deck of 
child windows: 

horizontal 

Arranges the child windows in the canvas horizontally in rows, from left to 
right. Decks of rows are arranged from top to bottom. 
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vertical 

Arranges the child windows in the canvas vertically in columns, from top to 
bottom. Decks of columns are arranged from left to right. 
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Alignment { 

topLeft, topCenter, topRight, centerLeft, centerCenter, 

centerRight, bottomLeft, bottomCenter, bottomRight 

}; 


Use the following enumerators to specify the alignment of child windows in a deck 

topLeft 

Aligns the child windows in the canvas to the top and left edge in the deck. 

topCenter 

Aligns the child windows in the canvas to the top edge, centered horizontally in 
the deck. 

topRight 

Aligns the child windows in the canvas to the top and right edge in the deck. 

centerLeft 

Aligns the child windows in the canvas to the left edge, centered vertically in 
the deck. 

centerCenter 

Aligns the child windows in the canvas to the center of the deck. 

centerRight 

Aligns the child windows in the canvas to the right edge, centered vertically in 
the deck. 

bottomLeft 

Aligns the child windows in the canvas to the bottom and left edge in the deck. 

bottomCenter 

Aligns the child windows in the canvas to the bottom edge, centered vertically 
in the deck. 

bottomRight 

Aligns the child windows in the canvas to the bottom and right edge in the 
deck. 


PackType { 
tight, 
even, 
expanded 
}; 


Use these enumerators to specify the spacing between child windows in decks 

tight 

Sizes the child windows to their minimum size and separates them within a 
deck by the pad amount only. 
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even 

Sizes child windows to their minimum size and spaces them so that 
corresponding windows in each deck are aligned. This gives the appearance of 
their being arranged in both rows and columns. As a result, child windows 
within a deck can be separated by more than the pad amount. This option has 
no affect if the set canvas has only one deck. 

expanded 

Similar to the enumerator even, except the child windows are expanded, rather 
than spaced by more than the pad amount. Child windows are expanded to the 
same size as the largest child window. 
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ISetCanvas::Style 


IBase 

IBitFlag 

ISetCanvas:: Style 


_.None. 

_ isetcv.hpp 

The nested class ISetCanvas::Style provides a set of valid canvas styles for the 
ISetCanvas::defaultStyle and ISetCanvas::setDefaultStyle functions, and for the 
constructor of the ISetCanvas (p. 1138) class. You can use these styles with the 
styles defined by the following nested class: 

ICanvas Styles (p. 34) 

IWindow Styles (Vol. II) 

Once you have constructed an ISetCanvas object, you can use ISetCanvas, ICanvas, 
and IWindow member functions to query and change its style. 

Note: To avoid conflicts that are noted in some of the alignment, deck, and pack 
styles, you can implement the wanted characteristics for the canvas by using 
the setAlignment, setDeckOrientation, and setPackType member functions of 
the ISetCanvas class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Functions 



Inherited Protected Data 
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ISplitCanvas 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ICanvas 

ISplitCanvas 


_.None. 


__isplitcv.hpp 

Member 

Page 

Constructor 

1161 

classDefaultStyle 

1166 

con vertT oGUIS ty le 

1164 

defaultStyle 

1164 

horizontal 

1166 

layout 

1165 

noSplitBars 

1167 

orientation 

1163 

orientationld 

1166 

resetSplitB arEdgeColor 

1160 

resetSplitB arMiddleColor 

1160 

setDefaultStyle 

1164 

setLayoutDistorted 

1162 


Member 

Page 

setOrientation 

1163 

setSplitB arEdgeColor 

1160 

setSplitB arMiddleColor 

1161 

setSplitB arThickness 

1163 

setSplitWindowPercentage 

1159 

splitB arEdgeColor 

1161 

splitB arMiddleColor 

1161 

splitB arThickness 

1164 

splitWindowPercentage 

1160 

vertical 

1167 

visibleRectangle 

1163 

“ISplitCanvas 

1162 


Objects of the ISplitCanvas class provide a way to split a window into two or more 
window panes by creating and adding controls. The number of controls you add 
determines the number of panes in the split canvas. 

You can separate the window panes using split bars (the default style). By dragging 
the split bars, a user can dynamically change the visible amount of each pane. 

You can stack the controls vertically (the default) or horizontally. 

Typically, you create a split canvas control with a frame window or another split 
canvas window as its parent and owner. Any window can serve this purpose. In 
addition, you might want to call IFrameWindow::setClient (Vol. II) to make the split 
canvas control the client window of a frame window. Then you can add other 


© IBM Corp. 1992, 1995 


ISetCanvas::Style 1157 






ISplitCanvas 


controls, such as list boxes, push buttons, or even another split canvas by creating 
each control with a split canvas for its parent. 

Note: You can make an IFrameWindow the child window of a split canvas only if it 
is the only child window of the canvas. You can, however, make the 
IFrameWindow the only child window of an IMultiCellCanvas by placing the 
IFrameWindow in a single expandable row and column and making the 
multiple-cell canvas one of many child windows of the split canvas. 

Do not change the z-order of the child windows of a split canvas without 
refreshing the canvas. Doing so results in unpredictable behavior. 

Controls are positioned in the window panes of a split canvas in the order you create 
them in, from left to right in a vertically split canvas and from top to bottom in a 
horizontally split canvas. Tabbing order is based on the order in which you create 
controls having the style IControl::tabStop (Vol. II). 

To specify what percentage of the split canvas a control occupies when the split 
canvas is initially displayed, use ISplitCanvas::setSplitWindowPercentage (p. 1159). 
The percentages you set determine the size of the window panes containing the 
controls, not the size of the controls themselves. Some testing might be necessary to 
determine the proper percentages to specify for each control to obtain the optimal 
initial appearance of the split canvas. 

Note: If the split canvas has split bars and the user drags the split bars, the 

percentages you set will change. Your percentage values determine the initial 
appearance of the split canvas and the controls it contains. The minimum size 
to which a user can size a pane is the width of the split bar. 

You can create a split canvas without split bars by using the style 
ISplitCanvas::noSplitBars (p. 1167). When you use this style, each pane 
maintains its size ratio to the other panes when users size the canvas. 
However, users cannot modify the percentage of the canvas occupied by a 
pane as they can when split bars are available. 

When the sum of the controls' percentages is equal to 100, each window pane is 
given its requested percentage of the split canvas. 

However, when the sum of the controls' percentages is less than or greater than 100, 
the percentages are converted to ratios. In this situation, the window panes 
containing the controls are sized on a one-to-one ratio, with each pane being given an 
equal size. 

For example, if your split canvas has three controls and you specify no percentages, 
each window pane is given the ratio of 10:10:10. Thus, each pane gets roughly 
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one-third of the window. The percentages are rounded off, so in this example the 
first window pane gets 34 percent of the split canvas and the other two panes get 33 
percent. 

If you set the percentages for either some of the controls or all of the controls, the 
total of the percentages (including any default percentages of 10) could still be less 
than or greater than 100. In this situation, the window panes that contain these 
controls are given a ratio determined by these percentages. 

For example, suppose you have three controls, as in the preceding example, but this 
time you let only the first two controls take the default percentage of 10. If you set 
the third control to 60 percent, the sum of the percentages is 80 (10+10+60=80), 
which is less than 100. However, in this case, instead of a ratio of 10:10:10, the 
window panes containing the controls are given a ratio of 10:10:60. Therefore, the 
first pane gets 10/80 of the split canvas (13 percent), the second pane gets 10/80 (12 
percent), and the third pane gets 60/80 (75 percent). 

If you set percentages for all of your controls and the sum of those percentages is less 
than or greater than 100, the window panes containing the controls are given a ratio 
determined by the percentages that you set. 

If a user changes the size of a split canvas, its window panes are sized to fill the split 
canvas by default. Each pane maintains its size ratio to the other panes in the canvas 
when this occurs. 

[_| Motif does not support the enumeration SplitBarEdge. The value of the edge is 

always zero. The enumerator splitBarMiddle specifies the thickness of the split bar. 


Public Functions 
Child Window Sizing 

Use these members to control the size of the child windows of the split canvas, through 
percentages (ratios). 

setSplitWindowPercentage 

Sets the percentage of the canvas occupied by the specified window. If you do not 
call this function, the split canvas gives the child window a default of 10 percent of 
its width or height. If the sum of the percentages of all child windows does not equal 
100, this value is treated as a ratio. 

Note: If the split canvas is already shown, this function does not update it 
immediately. You must call IWindow::refresh (Vol. II) to update the 
appearance of the canvas. 
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virtual ISplitCanvas& Supported On: 

setSpl itWindowPercentage( IWindow* window, PM, Motif 

unsigned long percentage); 

window The child window you are indirectly sizing. 

percentage The portion of the split window that the child window will occupy. 

splitWindowPercentage 

Returns the percentage of the width or height of the canvas currently occupied by the 
specified window. 


unsigned long 

splitWindowPercentage( IWindow* window); 
window The child window. 


Supported On: 

PM. Motif 


Colors 

Use these members to set and query the color of the middle or edge of a split bar. 


resetSplitBarEdgeColor 

Resets the color of the edges of the canvas's split bars, so the default edge color is 
used. 


virtual ISplitCanvas& Supported On: 

resetSpl i tBarEdgeColor (); PM, Motif Ignored 

resetSplitBarMiddleColor 

Resets the color of the interior of the canvas's split bars, so that the default color is 
used. 

virtual ISplitCanvas& 
resetSplitBarMiddleColor(); 

setSplitBarEdgeColor 

Sets the color for the edges of the canvas's split bars. 

virtual ISplitCanvas& Supported On: 

setSpl itBarEdgeColor( const IColor& color); PM. Motif Ignored 


Supported On: 

PM, Motif Ignored 
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setSplitBarMiddleColor 

Sets the color for the interior of the canvas's split bars. 


virtual ISplitCanvas& Supported On: 

setSpl itBarMiddleColor( const IColor& color); PM, Motif 

splitBarEdgeColor 

Returns the color of the edges of the canvas's split bars. 


Supported On: 

PM. Motif Ignored 

splitBarMiddleColor 

Returns the color of the interior of the canvas's split bars. 


virtual IColor 

splitBarEdgeColor() const; 


virtual IColor 

splitBarMiddleColor() const; 


Supported On: 

PM, Motif 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign ISplitCanvas 
objects because both the copy constructor and assignment operator are private functions. 

ISplitCanvas 


ISpl itCanvas( unsigned long windowldentifier. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IRectangle& initial Size = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

windowld Window identifier of the canvas you are constructing. 

Note: For OS/2, this value should be limited to the range 0 through 
65535. 

It is recommended that you: 

• Give unique identifiers to all windows in the same frame window. In 
the same window means that the frame window is the first frame in 
their parent window chain. 

• Give the client window a window ID of FID_CLIENT (0x8008). 

• Do not use the other FID_xxx values. 
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parent The parent window of the canvas you are constructing. You must specify 
a parent window. This constructor throws an IlnvalidParameter exception 
if you pass an IWindow* of 0. 

The parent window is primarily used for visible relationships. 

owner Owner window of the canvas you construct. 

Note: In OS/2, the owner window is primarily used for routing 

notification events and unprocessed messages. OS/2 also uses the 
owner window chain to inherit colors. 

In Motif, the owner window is only used for routing unprocessed 
messages. There is no concept of an owner in Motif. 

initial (Optional) The initial position and size of the canvas you are 

constructing. The initial position is the lower-left corner of the canvas 
relative to the lower-left corner of the parent window. 

style (Optional) The window's characteristics. These can be a combination of 

the ISplitCanvas::Style and the IWindow::Style. 


Exceptions 

IlnvalidParameter style contains an invalid combination of styles, style cannot contain both 

the ISplitCanvas "horizontal (p. 1166) and ISplitCanvas: vertical (p. 1167) 
styles. 


ISplitCanvas 


virtual 

"ISplitCanvas(); 


Supported On: 

PM, Motif 


Layout Support 

Layout members determine how this class sizes and positions its child windows or how this 
window will be laid out on another canvas. 


setLayoutDistorted 

Treats the following as changes to the layout of its child windows: 

• Changing the size of the canvas 

• Adding a child window 

• Removing a child window 


virtual ISplitCanvas& 

setLayoutDistorted( unsigned long layoutAttributesOn, 
unsigned long 1 ayoutAttributesOff); 


Supported On: 

PM, Motif 


1162 Open Class Library Reference 




ISplitCanvas 


Orientation 

These members control the orientation of the canvas' split bars. 

-Returns an enumerator Orientation (p. 1168) for the orientation of the canvas's split 
bars. 


Orientation 
orientation)) const; 


Supported On: 

PM, Motif 


setOrientation 

Sets the direction in which the canvas's split bars are drawn. 


virtual ISpl i tCanvas& Supported On: 

setOrientation) Orientation value); PM. Motif 

value Use the enumeration Orientation )p. 1168) to specify the direction. 


Painting Optimization 

These members provide a parent window with information that allows it to refresh the screen 
more efficiently. 

visibleRectangle 

Returns the portion of the window that the canvas actually paints. The parent 
window can perform painting optimizations by not painting this area. 

virtual IRectangle Supported On: 

visibleRectangle)) const; PM 


Split Bar Thickness 

Use these members to customize the thickness of the split bar. 


setSplitBarThickness 

Sets the thickness of the specified area of the split bar. 


virtual ISplitCanvas& 

setSplitBarThickness) SplitBarArea area, 

unsigned long thickness); 


Supported On: 

PM, Motif 


value Use the enumeration SplitBarArea )p. 1168) to specify the area. 
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thickness Thickness of the edge or middle in pixels. If you do not call this 

function, the thickness is the width of the system's frame sizing border. 


splitBarThickness 

Returns the thickness of the specified area of the split bar. 

unsigned long Supported On: 

spl i tBarThi ckness ( SplitBarArea area); PM. Motif 

value Use the enumeration SplitBarArea (p. 1168) to specify the area of the 
split bar. 


Styles 

Use these style members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

_ Returns the default style. The default style is classDefaultStyle (p. 1166) unless you 
have changed the style using setDefaultStyle (p. 1164). 

static Style Supported On: 

defaul tStyl e(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent split canvases. 

static void Supported On: 

setDefaultStyle( const Style& style); PM, Motif 

style A combination of ISplitCanvas::Style (p. 1166), ICanvas::Style (p. 34), 

and IWindow::Style (Vol. II) objects. 
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Inherited Public Functions 


ICanvas 

backgroundColor 

defaultStyle 

origDefaultButtonHandle 

convertToGUIStyle 

isTabStop 

setDefaultStyle 

defaultPushButton 

matchForMnemonic 

setLay outDi storted 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Layout Support 

Layout members determine how this class sizes and positions its child windows or how this 
window will be laid out on another canvas. 

.. Computes the position and size of all child controls. 


virtual ISplitCanvas& 
layout (); 


Supported On: 

PM, Motif 
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Inherited Protected Functions 


ICanvas 

areChildrenReversed 

layout 

registerCallbacks 

calcMinimumSize 

layoutSize 

setLay outSize 

fixupChildren 

passEventT oO wner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 

Notification Members 

These members allow observers to process changes to the window. 

-.Notification identifier provided to observers when the orientation of the split canvas 
changes. ISplitCanvas provides the new split canvas orientation value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). as an 
Orientation enumeration. 

static INotificationld const Supported On: 

orientationld; PM. Motif 


Styles 

Use these style members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 


classDefaultStyle 

Specifies the original default style for this class, which is ISplitCanvas::vertical I 
IWindow:: visible. 

static const Style Supported On: 

classDefaultStyle; PM. Motif 

__ Draws split bars horizontally, placing the panes top to bottom. 

Note: You cannot specify this style with ISplitCanvas::vertical (p. 1167). 
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static const Style Supported On: 

horizontal; PM, Motif 

— Specifies no split bars are used to separate panes. 


static const Style Supported On: 

noSplitBars; PM. Motif 

Draws split bars vertically, placing the panes left to right. This style is the default. 

Note: You cannot specify this style with ISplitCanvas::horizontal (p. 1166). 


static const Style 
vertical; 


Supported On: 

PM, Motif 


Inherited Public Data 


ICanvas 

classDefaultStyle 




IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColortd 

systemCommandld 

deletetd 

hiliteForegroundCoIorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Nested Classes 

ISplitCanvas contains the following nested classes: 
ISplitCanvas::Style (see page 1169) 


SplitBarArea { 
splitBarEdge, 
splitBarMiddle 
1 ; 


Use these enumerators to specify different areas of a split bar: 

splitBarEdge 

Specifies the top and bottom edges of a horizontal split bar, or the left and right 
edges of a vertical split bar. 

splitBarMiddle 

Specifies the interior of a split bar. 


Orientation { 

horizontalSplit, 
verticalSplit 
1 ; 

Use these enumerators to specify the direction of the canvas's split bars: 

horizontalSplit 

Draws split bars horizontally, placing the panes top to bottom. 

verticalSplit 

Draws split bars vertically, placing the panes left to right. 
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IBase 

IBitFlag 

ISplitCanvas: :Style 


_.None. 

_isplitcv.hpp 

The nested class ISplitCanvas::Style provides a set of valid split canvas styles for the 
ISplitCanvas::defaultStyle and ISplitCanvas::setDefaultStyle functions, and for the 
constructor of the ISplitCanvas (p. 1157) class. You can use these styles with the 
styles defined by the following nested classes: 

ICanvas Styles (p. 34) 

IWindow Styles (Vol. II) 

Once you have constructed an ISplitCanvas object, you can use ISplitCanvas, 
ICanvas, and IWindow member functions to query and change its style. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 
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ISplitCanvas: :Style 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IStringGenerator 


IBase 

IStringGenerator 


_.None. 


_ istrgen.hpp 


Member 

Page 

Member 

Page 

Constructor 

1172 

stringFor 

1173 

operator = 

1172 

“IStringGenerator 

1173 


Objects of the IStringGenerator class manage the translation of objects to their IString 
form. Use the IStringGenerator: :stringFor member function to translate an object to 
its IString representation. Call it on an object-by-object basis. In the default case ( no 
IStringGeneratorFn (p. 1175) ), the object should support the operators or be an 
Object*, where the Object class has an asString member function. 

The IStringGenerator::stringFor member function processes as follows: 

• If no IStringGeneratorFn object has been set (the default), then it uses an object's 
asString member function for translation. 

• If an optional IStringGeneratorFn has been set, it uses the 
IStringGeneratorFn::stringFor member function. 

Note: IStringGeneratorFn objects represent functions. Objects of the 
IStringGeneratorMemberFn (p. 1178) and 

IStringGeneratorRefMemberFn (p. 1181) classes represent member functions 
and differ in how they treat the object parameter in the stringFor member 
function. 

Create and use IStringGenerator objects by following these steps: 

• Create an IStringGeneratorFn subclass object containing the function to be called 
to generate an IString. 

• Create an IStringGenereator object initializing it with the IStringGeneratorFn 
subclass object. 
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• Call the IStringGenerator::stringFor member function passing as the parameter the 
object you want a string generated for. 

Note: IStringGeneratorFn, as an abstract base class, establishes the protocol for 

specifying a function to translate an object to an IString. Subclass this class 
and implement the stringFor member function to define the calling convention 
and call the stored function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. The copy constructor and operatoi- ensure 
that the contained generator function objects are reference counted properly. 

IStringGenerator 

[j IStringGenerator( Supported On: 

const IReference < IStringGeneratorFn < Element > >& PM 

generatorFunction = 0); 

You create a string generator object using an optional IStringGeneratorFn. 
generatorFunction 

A pointer (IReference) to an existing IStringGeneratorFn derived class 
object. If it is specified, subsequent calls to stringFor will use this 
function to produce strings for the given object. 

Note: The pointer, IReference, object ensures the generator function 
(which is of type IRefCounted) is reference counted properly. 

3 IStringGenerator( Supported On: 

const IStringGenerator < Element >& stringGenerator); PM 

You can create a string generator object using another IStringGenerator. This ensures 
that the reference counting of the IStringGeneratorFn object is done properly. 

stringGenerator 

A string generator. 

_ Assign one string generator to another. This ensures that the reference counting of 
the IStringGeneratorFn object is done properly. 

stringGenerator 

A string generator. 
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IStringGenerator < Element >& 
operator =( 

const IStringGenerator < Element >& stringGenerator); 


Supported On: 

PM 


IStringGenerator 


virtual 

'IStringGenerator(); 


Supported On: 

PM 


Generate String 

Use this member to translate an object to its IString form. 

_ Obtains an IString version of the element. If a local IStringGeneratorFn has been 
set, then it is used. Otherwise, the element's asString member function generates the 
IString. 

element Reference to the object for which it generates the string. 

Note: For the default case (no IStringGeneratorFn) the element should 
natively support operators or the element must be an Object*, 
where the Object class has an asString member function. 


IStringGeneratorRefMemberFn and IStringGeneratorMemberFn (IStringGeneratorFn 
subclasses) contain member functions that take no parameters. They support invoking 
these member functions on Object* elements (element is a pointer) and concrete 
Object elements (element is not a pointer), respectively. If you need additional string 
generation support, create your own IStringGeneratorFn subclass. 

IString Supported On: 

stringFor( const Element& element) const; PM 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IStringGeneratorFn 


IBase 

IVBase 

IRefCounted 

IStringGeneratorFn 


IStringGeneratorMemberFn 

IStringGeneratorRefMemberFn 


—istrgen.hpp 


Member 

Page 

Constructor 

1176 

stringFor 

1176 

“IStringGeneratorFn 

1176 


The IStringGeneratorFn template class is an abstract base class defining the protocol 
for storing and calling functions to generate IStrings. Objects of this class represent 
functions to be called when the stringFor function is called. The stringFor pure 
virtual function accepts an object reference of the template class type. 

Note: IStringGenerator (p. 1171) does the following: 

• Uses these objects (calls IStringGeneratorFn: :stringFor) to generate 
IStrings. 

• Accepts an optional parameter, a reference to an IStringGeneratorFn on 
its constructor. 

Use the subclasses IStringGeneratorMemberFn and IStringGeneratorRefMemberFn or 
create your own subclass to represent functions. These subclasses do two things: 

• On the constructor, save a pointer to the function the object represents 

• Implement stringFor to call the stored function 

These objects are reference counted to manage their destruction. 

IStringGeneratorMemberFn and IStringGeneratorRefMemberFn objects represent 
member functions of the template class type. Review these classes for example 
usage. 
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Public Functions 
Constructors 

You do not create objects of this class. It is an abstract base class. 

IStringGeneratorFn 

IStringGeneratorFn(); 

"IStringGeneratorFn 

virtual 

'IStringGeneratorFn(); 


Supported On: 

PM 


Supported On: 

PM 


Generate String 

Establishes the protocol for generating an IString for the object parameter. Subclasses implement 
this function to generate an IString for that object. 

_Is a pure virtual function. It accepts an object reference as a parameter; it is this 
object for which subclass objects generate a string. IStringGeneratorFn subclasses 
override this function to call the appropriate member function, with the appropriate 
number of parameters. 

virtual IString Supported On: 

stringFor( const T& object) = 0; PM 


Inherited Public Functions 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 
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IBase 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IStringGeneratorMemberFn 


IBase 

IVBase 

IRefCounted 

IStringGeneratorFn 

IStringGeneratorMemberFn 


_.None. 

_istrgen.hpp 


Member Page 

Constructor 1179 

stringFor 1179 

“IStringGeneratorMemberFn 1179 


The IStringGeneratorMemberFn template class is an IStringGeneratorFn derived class. 
It dispatches C++ member functions against an object to generate an IString. These 
objects represent member functions of class T, where T is the template argument. 
Objects of this class apply the stored member function against class T objects in the 
stringFor member function, where object is a reference to a class T object. 

The constructor for these objects requires a pointer to a class T member function; this 
member function returns an IString and accepts no arguments. Subclass this class to 
support member functions with additional parameters. 

The following example creates an IStringGeneratorMemberFn object: 

class MyClass { 
public: 

IString myStringO 

{ 

// Code to generate a string 


// . 

}; 

II... 

MyClass myObj; 

IStringGeneratorMemberFn<MyClass> * genFunction = new 
IStringGeneratorMemberFn<MyClass>( MyClass::myString ); 
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Note: Objects of the IStringGeneratorMemeberFn class assume that the object 
passed on the stringFor member function is not a pointer. 
IStringGeneratorRefMemberFn objects generate strings from pointers to 
objects. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IStringGeneratorMemberFn 

Create from a pointer to a member function of class T, where T is the template 
argument. The member function must return an IString and accept no arguments; 
also, it is not a const function.. 

member A pointer to the member function. 


IStringGeneratorMemberFn ( 

IString ( T::* member ) ( )); 


Supported On: 

PM 


IStringGeneratorMemberFn 


virtual 

'IStringGeneratorMemberFnO; 


Supported On: 

PM 


Generate String 

Use this member to generate an IString from an object. 

_Calls the appropriate member function on the object reference parameter. The called 
member function is initialized from the parameter on the IStringGeneratorMemberFn 
constructor. 

object Reference to the object against which it dispatches the member function. 

Note: The object parameter must be an object of type T (where T is the 
template class argument) and not a pointer. 


virtual IString 
stringFor( const T& object); 


Supported On: 

PM 
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Inherited Public Functions 


IStringGeneratorF n 

stringFor 




IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IStringGeneratorRefMemberFn 


IBase 

IVBase 

IRefCounted 

IStringGeneratorFn 

IStringGeneratorRefMemberFn 


_.None. 

_istrgen.hpp 


Member Page 

Constructor 1182 

stringFor 1183 

“IStringGeneratorRefMemberFn 1182 


The IStringGeneratorRefMemberFn template class is an IStringGeneratorFn derived 
class. It dispatches C++ member functions against an object pointer to generate an 
IString. These objects represent member functions of class U to be applied against 
objects of type T, where T and U are template arguments and T is defined as typedef 
U* T;. This makes objects of type T the pointers to objects of class U. Objects of 
this class apply the stored member function against type T objects in the 
stringFor(const T& object) function, where object is a reference to a type T object. 

The constructor for these objects requires a pointer to a class U member function; this 
member function returns an IString and accepts no arguments. Subclass this class to 
support member functions with additional parameters. 


The following example creates an IStringGeneratorRefMemberFn object: 
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class MyClass { 
public: 

IString myStringO 

{ 

// Code to generate a string 


// . 

}; 

II... 

typedef MyClass * pMyClass; 

MyClass myObj; 

IStringGeneratorRefMemberFn<MyClass> * genFunction = new 

IStringGeneratorRefMemberFn<MyClass>( pMyClass, MyClass::myString ); 


Note: Objects of the IStringGeneratorRefMemeberFn class assume that the object 
passed on the stringFor member function is pointer or an object that supports 
the operator->. IStringGeneratorMemberFn objects generate strings from 
objects which are not pointers. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IStringGeneratorRefMemberFn 

Create from a pointer to a member function of class U, where U is a template 
argument. The member function must return an IString, accept no arguments, and be 
a non-const function. 

member A pointer to the member function. 


IStringGeneratorRefMemberFn( IString ( U::* member ) ( )); Supported On: 

PM 

This constructor requires a pointer to a class U member function. This member 
function should return an IString, accept no parameters and be a non-const function. 

IStringGeneratorRefMemberFn 


virtual 

'IStri ngGeneratorRefMemberFn(); 


Supported On: 

PM 
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Generate String 

Use this member to generate an IString from an object pointer. 

_This function calls the appropriate member function on the object reference 
parameter. The called member function is initialized from the parameter on the 
IStringGeneratorMemberFn constructor. It assumes the object parameter is a pointer. 

object Reference to the object against which it dispatches the member function. 

Note: The object parameter must be an object of type T, which is a 
pointer to an object of type U (where T and U are the template 
class arguments) and class U contains the member function that is 
dispatched. 

virtual IString Supported On: 

stringFor( const T& object); PM 


Inherited Public Functions 


IStringGeneratorF n 

stringFor 




IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IToolBar 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ICanvas 

ISetCanvas 

IToolBar 


_.None. 


__itbar.hpp 


Member 

Page 

Member 

Page 

Constructor 

1185 

floatingFrame 

1188 

addAsFirst 

1190 

floatingPosition 

1188 

addAsLast 

1191 

floatingTitle 

1188 

addAsNext 

1191 

initialize 

1196 

addAsPrevious 

1191 

isExpanded 

1187 

allowsDragDrop 

1186 

isMisfitFilteringEnabled 

1188 

buttonBitmapAndTextVisible 

1197 

location 

1194 

buttonBitmapVisible 

1197 

moveAfter 

1191 

buttonTextVisible 

1197 

moveBefore 

1192 

buttonView 

1190 

moveToFirst 

1192 

calcMinimumSize 

1196 

moveToLast 

1192 

classDefaultStyle 

1198 

noDragDrop 

1198 

collapse 

1187 

remove 

1192 

con vertT oGUISty le 

1189 

setButtonView 

1190 

createFloatingFrame 

1195 

setDefaultGroupPad 

1193 

createT oolB arContainer 

1196 

setDefaultMargin 

1193 

defaultGroupPad 

1193 

setDefaultMisfitWidth 

1194 

defaultMargin 

1193 

setDefaultPad 

1194 

defaultMisfitW idth 

1193 

setDefaultStyle 

1189 

defaultPad 

1193 

setFloatingPosition 

1188 

defaultStyle 

1189 

setFloatingTitle 

1189 

disableDragDrop 

1186 

setLayoutDistorted 

1185 

disableMisfitFiltering 

1187 

setLocation 

1194 

enableDragDrop 

1187 

toolBarAt 

1186 

enableMisfitFiltering 

1187 

toolB arContainer 

1190 

expand 

1187 

windowAt 

1186 

filter 

1196 

'IToolBar 

1186 

filterMisfits 

1198 
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The IToolBar class creates and manages a tool bar for a frame window. 


Public Functions 
Canvas Layout 

Use these members to provide support for canvas layout. 


setLayoutDistorted 

Treats a minimum size change for a child window like a layout change. This 
function optimizes the layout of the tool bar during initialization. 


virtual IToolBar& 

setLayoutDistorted( unsigned long layoutAttributeOn, 
unsigned long 1ayoutAttributeOff); 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IToolBar objects 
because both the copy constructor and assignment operator are private functions. 


IToolBar 

Q IToolBar( unsigned long identifier, Supported On: 

IFrameWindow* owner, PM 

Location location = aboveClient, 

Boolean groupWithPreceding = false, 
const Style& style = defaultStyle ( )); 

Creates a tool bar as the last tool bar in the tool bar area defined by the 
frameLocation. 

If groupWithPreceding is true, the tool bar is placed on the same row or column as 
the last tool bar in the specified frame location (if one exists). If an 
IToolBarContainer is needed for the location indicated, it is created automatically 
when you use this constructor. 

2 IToolBar( unsigned long identifier, Supported On: 

IToolBar* precedingToolBar, PM 

Boolean groupWithPreceding = false, 
const Style& style = defaultStyle ( )); 

Creates a tool bar relative to an existing tool bar. 
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"IToolBar 


virtual 
"IToolBar(); 


Supported On: 

PM 


Cursor Members 

Use these members to query the IToolBar at the current FrameCursor position or the IWindow at 
the current WindowCursor position. 

-.Returns a pointer to the IToolBar at the cursor position. 


static IToolBar* 

toolBarAt( const FrameCursor& cursor); 


Supported On: 

PM 


Exceptions 

IlnvalidParameter An invalid cursor was specified. 


.. Returns a pointer to the IWindow at the cursor position. 


IWindow* 

windowAt( const WindowCursor& cursor) const; 


Supported On: 

PM 


Drag and Drop Support 

Use these members to set and query whether the tool bar supports drag and drop. 

allowsDragDrop 

Returns true if the tool bar supports drag and drop. 

Bool ean Supported On: 

al lowsDragDrop() const; PM 


disableDragDrop 

Prevents dragging of the tool bar, as well as the objects that reside on the tool bar, 
such as a tool bar button. Prevents drops from occurring on the tool bar. 

virtual ITool Bart Supported On: 

disableDragDrop(); PM 
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enableDragDrop 

Enables dragging of the tool bar, as well as the objects that reside on the tool bar, 
such as a tool bar button. Enables drops on the tool bar. 

virtual IToolBart Supported On: 

enableDragDrop( Boolean enable = true); PM 


Expanding and Collapsing the Tool Bar 

Use these members to expand or collapse the height of the tool bar when it is floating. If the 
tool bar is collapsed, only the title bar of the floating frame is displayed. 

.Displays only the title of tool bar when it is floating. 


virtual IToolBar& Supported On: 

collapse(); PM 

Displays the entire tool bar when it is floating. 


virtual IToolBar& Supported On: 

expand( Boolean expand = true); PM 

_ Returns true if the entire tool bar is displayed when it is floating. 


Boolean 

isExpanded() const; 


Supported On: 

PM 


Filter Misfits 

Use these members to query or change the filterMisfits style for IToolBar objects. 

disableMisfitFiltering 

Removes the filterMisfits style from the tool bar. 

IToolBart 

di sabl eMi sfi tFi 1 tering (); 

enableMisfitFiltering 

Sets the filterMisfits style for the tool bar. 

ITool Bart Supported On: 

enabl eMi sfi tFil teri ng ( Boolean enable = true); PM 


Supported On: 

PM 
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isMisfitFiltering Enabled 

Returns true if the filterMisfits style is set for the tool bar. 

Bool ean Supported On: 

isMisfitFilteringEnabled() const; PM 


Floating Tool Bar 

Use these members to set or query information about a floating tool bar. 


floatingFrame 

Returns the IToolBarFrameWindow object that contains this tool bar. A 0 is returned 
if this tool bar is not currently in a floating frame window. 


virtual IToolBarFrameWindow* 
floatingFrame(); 


Supported On: 

PM 


floatingPosition 

Returns the current position of the frame window that encloses the floating tool bar 
(relative to the owning frame window used to construct the tool bar). 

If the tool bar is not floating, the position the tool bar would occupy if it were 
floating is returned instead. 

I Po i n t Supported On: 

floatingPosition() const; PM 

_ Returns the title text of the floating frame window. 

If the tool bar is not floating, the title that would be used if the tool bar were floating 
is returned instead. 

IString 

floatingTitle() const; 

setFloatingPosition 

Sets the position of the frame window that encloses the floating tool bar. The 
position is relative to the owning frame window used to construct the tool bar. 

If the tool bar is not currently floating, the position is saved and used if the tool bar 
location is changed to floating. 


Supported On: 

PM 
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virtual IToolBar& 

setFloatingPosition( const IPoint& frameRelativePosition); 


Supported On: 

PM 


setFloatingTitle 

Sets the title text of the floating frame window. 

If the tool bar is not floating, the title is saved and used when the tool bar location is 
changed to floating. 


Q virtual IToolBar& Supported On: 

setFloatingTitle( const IResourceId& text); PM 


§ virtual IToolBar& Supported On: 

setFl oati ngTi tl e( const char* text); PM 


Styles 

Use these members to set and query tool bar styles. You can use these styles with the styles 
defined by the following nested classes: 

IWindow Styles (Vol. II) 

ICanvas Styles (p. 34) 

ISetCanvas Styles (p. 1147) 


convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

-.Returns the default style. The default style is classDefaultStyle unless you have 
changed the style using setDefaultStyle. 

static Style Supported On: 

defaultStyle(); PM 


setDefaultStyle 

Sets the default style for all subsequent tool bars. 
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style Use the styles provided by IToolBar::Style to specify the default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM 


Tool Bar Button Behavior 

Use these members to affect the appearance of any IToolBarButton objects in the tool bar. 
..Returns the current view of IToolBarButton objects in the tool bar. 

IToolBarButton: :View Supported On: 

buttonView() const; PM 


set Button View 

Changes the IToolBarButton members of the tool bar to the value of 
IToolBarButton::view. Valid values are IToolBarButton::bitmapView, 
IToolBarButton::textView, and IToolBarButton::bitmapAndText. 

virtual IToolBar& Supported On: 

setButtonView( IToolBarButton: :View buttonView); PM 


Tool Bar Container 

Use these members to access IToolBarContainer objects. 


toolBarContainer 

Returns a pointer to the IToolBarContainer object that contains this tool bar. A 0 is 
returned if this tool bar is not currently in a tool bar container. 


virtual IToolBarContainer* 
toolBarContainer() const; 


Supported On: 

PM 


Tool Bar Contents 

Use these members to add and remove items in the tool bar. Explicit addition and removal of 
IToolBar items is necessary to enable correct direct manipulation behavior and to ensure that 
misfits are properly filtered in and out of the tool bar. 

- Adds the window as the first item in the tool bar. 

If startNewGroup is true, the window is placed by itself into a new group. 

Otherwise, the window becomes part of the first group in the tool bar. 
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virtual IToolBar& 
addAsFirst( IWindow* window. 

Boolean startNewGroup = false); 

_Adds the window as the last item in the tool bar. 


Supported On: 

PM 


If startNewGroup is true, the window is placed by itself into a new group. 
Otherwise, the window becomes part of the last group in the tool bar. 


virtual IToolBar& Supported On: 

addAsLast( IWindow* window, PM 

Boolean startNewGroup = false); 

_Adds the window as the next item in the tool bar immediately after the reference 
window. 

If startNewGroup is true, the window starts a new group. Otherwise, the window 
becomes part of the same group as the reference window. 


virtual IToolBar& Supported On: 

addAsNext( IWindow* window, PM 

IWindow* referenceWindow, 

Boolean startNewGroup = false); 


addAsPrevious 

Adds the window as the previous item in the tool bar immediately before the 
reference window. 

If startNewGroup is true, the window starts a new group. Otherwise, the window 
becomes part of the same group as the reference window. 


virtual IToolBar& Supported On: 

addAsPrevious( IWindow* window, PM 

IWindow* referenceWindow, 

Boolean startNewGroup = false); 

-Moves the window so that it immediately follows the reference window. 

If startNewGroup is true, the window starts a new group. Otherwise, the window 
becomes part of the same group as the reference window. 

Note: This function is equivalent to calling the remove and addAsNext methods. 
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virtual IToolBar& Supported On: 

moveAfter( IWindow* window, PM 

IWindow* referenceWindow, 

Boolean startNewGroup = false); 

_Moves the window so that it immediately precedes the reference window. 

If startNewGroup is true, the window starts a new group. Otherwise, the window 
becomes part of the same group as the reference window. 

Note: This function is equivalent to calling the remove and addAsPrevious methods. 


virtual IToolBar& 
moveBefore( IWindow* window, 

IWindow* referenceWindow, 

Boolean startNewGroup = false); 

—Moves the window so that it is the first window in the tool bar. 

If startNewGroup is true, the window starts a new group. Otherwise, the window 
becomes part of the first group in the tool bar. 

Note: This function is equivalent to calling the remove and addAsFirst methods. 


Supported On: 

PM 


virtual IToolBar& Supported On: 

moveToFirst( IWindow* window, PM 

Boolean startNewGroup = false); 

—Moves the window so that it is the last window in the tool bar. 

If startNewGroup is true, the window starts a new group. Otherwise, the window 
becomes part of the last group in the tool bar. 

Note: This function is equivalent to calling the remove and addAsLast methods. 


virtual IToolBar& 
moveToLast( IWindow* window. 

Boolean startNewGroup = false); 

Removes the window from the tool bar. 


Supported On: 

PM 


virtual IToolBar& 
remove( IWindow* window); 


Supported On: 

PM 


Tool Bar Defaults 

Use these static members to affect the appearance of all IToolBar objects in the application. 
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defauItGroupPad 

Returns the current number of pels of padding added between groups in tool bars. 

static unsigned long Supported On: 

defaultGroupPad(); PM 


defaultMargin 

Returns the current number of pels of margin added around windows in tool bars. 

static ISize Supported On: 

defaul tMargi n (); PM 

defaultMisfitWidth 

Returns the current width used to filter oversized windows from tool bars. 


static unsigned long Supported On: 

defaul tMi sfi tWidth (); PM 

_ Returns the current default number of pels use to separate windows in tool bars. 


static long 
defaultPad(); 


Supported On: 

PM 


setDefauItGroupPad 

Sets the number of pels of padding between groups of windows in the tool bar. This 
pad value is added to any window that returns true from IWindow::isGroup. 

static void Supported On: 

setDefaultGroupPad( unsigned long pixelsOfGroupPad = 8); PM 


setDefaultMargin 

Sets the number of pels of margin around windows in the tool bar. The 
sizeOfMargin value is applied directly to a horizontal tool bar and rotated for a 
vertical tool bar. In a horizontal tool bar, sizeOfMargin.width is added to the left and 
right of the tool bar windows and sizeOfMargin.height is added to the top and bottom 
of tool bar windows. The initial sizeOfMargin value is ISize(7,4). 

static void Supported On: 

setDefaultMargin( const ISize& sizeOfMargin = ISize ( 7 , PM 

4 )); 
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setDefaultMisfitWidth 

Sets the width value to be used for filtering windows when a tool bar contains the 
style IToolBar::filterMisfits. 

The initial setDefaultMisfitWidth is 100 pels. 

static void Supported On: 

setDefaultMisfitWidth( unsigned long maximumWidth = 100); PM 


setDefaultPad 

Sets the number of pels of padding between windows added to the tool bar. The 
initial default is to overlap the members of a group by one pel. 

static void Supported On: 

setDefaultPad( long pixelsOfPad = - 1); PM 


Tool Bar Location 

Use these members to set and query the tool bar location. 
Returns the current location of the tool bar. 


Location Supported On: 

location() const; PM 

_Sets a new location for the tool bar. 


virtual IToolBar& 
setLocation( Location location); 


Supported On: 

PM 


Inherited Public Functions 


ISetCanvas 

alignment 

packType 

setLayoutDistorted 

convertToGUIStyle 

pad 

setMargin 

deckCount 

position 

setPackType 

deckOrientation 

setAlignment 

setPad 

defaultStyle 

setDeckCount 

setText 

groupPad 

setDeckOrientation 

size 

margin 

setDefaultStyle 

text 


1194 Open Class Library Reference 





IToolBar 


ISetCanvas 

moveSizeTo 

setGroupPad 

topHandle 


ICanvas 

backgroundColor 

defaultStyle 

origDefaultButtonHandle 

convertToGUIStyle 

isTabStop 

setDefaultStyle 

defaultPushButton 

matchForMnemonic 

setLay outDi storted 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Initialization 

These members initialize a tool bar. 

createFloatingFrame 

Creates a new IToolBarFrameWindow to be used for the floating tool bar. 

virtual IToolBarFrameWindow* Supported On: 

createFloatingFrame( IFrameWindow* owner); PM 
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createT ool BarContainer 

Creates a new IToolBarContainer to be used for the tool bar. 


virtual IToolBarContainer* Supported On: 

createToolBarContainer( IFrameWindow* frame); PM 

Checks if misfits need to be filtered in or filtered out based on the orientation of the 
tool bar and the current tool bar style. 

virtual IToolBar& Supported On: 

filter(); PM 

Initializes the tool bar window when the tool bar needs a tool bar container or 
floating frame, or when the first child window is added to the toolbar. Initialization 
is delayed so derived classes can override the createToolBarContainer and 
createFloatingFrame methods. 


virtual IToolBar& 
initial ize(); 


Supported On: 

PM 


Layout 

Layout is information used by the canvas classes to provide dialog-like behavior. 

calcMinimumSize 

Returns the recommended minimum size for this tool bar. If isExpanded is false, the 
tool bar has have a height of 0. Otherwise, this returns the minimum size required to 
display the contents of the tool bar. 

virtual ISize Supported On: 

calcMinimumSizeO const; PM 


Inherited Protected Functions 


ISetCanvas 

expandForText 

layout 



ICanvas 

areChildrenReversed 

layout 

registerCallbacks 

calcMinimumSize 

layoutSize 

setLayoutSize 
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ICanvas 

fixupChildren 

passEventT oOwner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
Styles 

Use these members to set and query tool bar styles. You can use these styles with the styles 
defined by the following nested classes: 

IWindow Styles (Vol. II) 

ICanvas Styles (p. 34) 

ISetCanvas Styles (p. 1147) 


buttonBitmapAndTextVisible 

Displays both the button text and bitmap for IToolBarButton objects that are added 
into the tool bar. 

static const Style Supported On: 

buttonBitmapAndTextVisible; PM 

buttonBitmapVisible 

Displays only the bitmap for IToolBarButton objects that are added into the tool bar. 

static const Style Supported On: 

buttonBitmapVisible; PM 

buttonTextVisible 

Displays only the button text for IToolBarButton objects that are added into the tool 
bar. 


static const Style 
buttonTextVisible; 


Supported On: 

PM 
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classDefaultStyle 

Specifies the original default style for this class, which is IToolBar::filterMisfits, 
IToolBar::buttonBitmapVisible, and IWindow::visible. 

static const Style Supported On: 

classDefaultStyle; PM 

-.Automatically filters out any windows in the tool bar that exceed the misfit width 
when the tool bar is oriented vertically. 

The purpose of this style is to save screen space when a tool bar is oriented 
vertically. If a wide control is displayed, there would be wasted space to the right of 
tool bar buttons and other smaller controls. 

If a tool bar is oriented vertically and then later reoriented horizontally, controls that 
were filtered out due to the filterMisfits style are automatically filtered back into the 
tool bar. 

static const Style Supported On: 

filterMisfits; PM 

- Disables the dragging of a tool bar or tool bar buttons that reside within the tool bar 
and disables drops onto the tool bar or tool bar buttons. 


static const Style 
noDragDrop; 


Supported On: 

PM 


Inherited Public Data 


ISetCanvas 

border 

deckOrientationld 

packExpanded 

bottomAlign 

decksByGroup 

packTight 

center Align 

horizontalDecks 

rightAlign 

centerV erticalAlign 

leftAlign 

textld 

classDefaultStyle 

packEven 

topAlign 


ICanvas 

classDefaultStyle 
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IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IToolBar contains the following nested classes: 

IToolBar::Style (see page 1203) 

IToolBar::WindowCursor (see page 1204) 
IToolBar::FrameCursor (see page 1201) 


Location { 

aboveClient, 
hidden 
}; 


belowClient. 


1eftOfClient, rightOfClient, floating. 


Use these enumerators to specify the location of the tool bar. 

aboveClient 

The tool bar is above the client window. 

belowClient 

The tool bar is below the client window. 

leftOfClient 

The tool bar is to the left of the client window. 
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rightOfCIient 

The tool bar is to the right of the client window. 


floating 

The tool bar is a child of an enclosing frame window that is a child of the 
desktop. If a user closes a floating tool bar, the location of the tool bar is set 
to hidden. 


hidden 

The tool bar is not displayed on the screen and is not visible to the user. 
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IToolBar::FrameCursor 


IBase 

IVBase 

IToolBar: :FrameCursor 


_.None. 


—itbar.hpp 


Member 

Page 

Member 

Page 

Constructor 

1201 

setToFirst 

1202 

FrameCursor 

1201 

setToNext 

1202 

invalidate 

1202 

'FrameCursor 

1201 

is Valid 

1202 




The IToolBar::FrameCursor class creates and manages a cursor for iterating over the 
tool bars that are owned by a frame window. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


FrameCursor 

FrameCursor( const IFrameWindow* frame); Supported On: 

PM 

Creates an IToolBar::FrameCursor to iterate over the tool bars for the specified frame 
window. 

TrameCursor 


virtual 

'FrameCursorO; 


Supported On: 

PM 
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Cursor Functions 

Use these members to iterate over the tool bars that are owned by a frame window. 
-Invalidates the cursor. 


virtual void Supported On: 

invalidate(); PM 

Returns true if the cursor is valid. 


virtual Boolean Supported On: 

isValid() const; PM 

.Initializes the cursor to point to the first tool bar. 


virtual Boolean Supported On: 

setToFirst(); PM 

... Advances the cursor to point to the next tool bar. 


virtual Boolean 
setToNext(); 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



1202 Open Class Library Reference 




IToolBar::Style 



IToolBar::Style 


IBase 

IBitFlag 

IToolBar::Style 


_.None. 

_ itbar.hpp 

The nested class IToolBar::Style provides a set of valid styles for the static member 
functions of the class IToolBar. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IToolBar::WindowCursor 


IBase 

IVBase 

IToolBar:: WindowCursor 


_.None. 


—itbar.hpp 


Member 

Page 

Member 

Page 

Constructor 

1204 

setToNext 

1205 

invalidate 

1205 

WindowCursor 

1204 

is Valid 

1205 

~W indo wCursor 

1204 

setToFirst 

1205 




The IToolBar::WindowCursor class creates and manages a cursor for iterating over 
the windows that have been added to a toolbar. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


WindowCursor 


WindowCursor( const IToolBar* toolbar); Supported On: 

PM 

Creates an IToolBar::WindowCursor to iterate over the windows that have been added 
to the specified tool bar. 

WindowCursor 

virtual Supported On: 

'WindowCursor(); PM 
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IToolBar:: WindowCursor 


Cursor Functions 

Use these members to iterate over the windows that have been added to a toolbar. 

-Invalidates the cursor. 

virtual void 
inval idate(); 

Returns true if the cursor is valid 

virtual Boolean 
isValid() const; 

-Initializes the cursor to point to the first window in the tool bar. 

virtual Boolean 
setToFirst(); 

-Advances cursor to point to the next window in the tool bar. 

virtual Boolean 
setToNext(); 


Inherited Public Functions 



Inherited Protected Data 
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PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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IToolBarButton 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

ICustomButton 

IToolBarButton 


_.None. 

__itbarbut.hpp 


Member 

Page 

Member 

Page 

Constructor 

1208 

re setT ran sparentColor 

1213 

allowsDragDelete 

1209 

setBitmap 

1207 

bitmap 

1207 

setDefaultStyle 

1212 

bitmapAndTextVisible 

1216 

setDefaultTran sparentColor 

1213 

bitmapSize 

1207 

setLatchedB itmap 

1207 

bitmapVisible 

1217 

setLayoutDistorted 

1208 

calcMinimumSize 

1216 

setStandardBitmapSize 

1210 

classDefaultStyle 

1217 

setS tandardT extLines 

1211 

clearDefaultTransparentColor 

1213 

setStandardTextWidth 

1211 

convertT oGUISty le 

1212 

setTransparentColor 

1214 

defaultStyle 

1212 

set View 

1214 

defaultTransparentColor 

1213 

standardB itmapS ize 

1211 

disableDragDelete 

1210 

standardFormat 

1217 

enableDragDelete 

1210 

standardTextLine s 

1211 

hasTransparentColor 

1213 

standardT extW idth 

1211 

isBitmapVisible 

1214 

textVisible 

1217 

isDefaultTransparentColorSet 

1213 

transparentColor 

1214 

isStandardFormat 

1210 

useldForB itmap 

1218 

isTextVisible 

1214 

useldForText 

1218 

latchedBitmap 

1207 

view 

1214 

noDragDelete 

1217 

'IToolBarButton 

1209 


The IToolBarButton class creates and manages the tool bar button control window. 
IToolBarButton provides support for displaying a bitmap, text, or bitmap and text on 
a button. 
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Public Functions 
Bitmaps 

Use these members to set and query the bitmaps that are displayed for a button. If a latched 
bitmap is not supplied, the default bitmap is also used for the latched state. If the tool bar button 
has a style of standardFormat and the bitmap is larger than the standard bitmap size, then the 
bitmap is resized to the standard bitmap size when setBitmap or setLatchedBitmap is used. You 
can also specify a transparent color for use when drawing the bitmap. 

-Returns the handle of the default bitmap. 

IBitmapHandle 
bitmap() const; 

- Returns the size of the current bitmap 

virtual ISize Supported On: 

bitmapSize() const; PM 


Supported On: 

PM 


latchedBitmap 

Returns the handle of the bitmap that is displayed when the button is in the latched 
state. 


IBi tmapHandl e Supported On: 

latchedBitmap() const; PM 

-Sets the bitmap to be used for the unlatched (default) button state. 


Q virtual IToolBarButton& Supported On: 

setBitmap( const IResourceId& bitmapld); PM 

§ virtual IToolBarButton& Supported On: 

setBitmap( const IBi tmapHandl e& handle); PM 

g virtual ITool BarButton& Supported On: 

setBitmap( unsigned long id); PM 


setLatchedBitmap 

Sets the bitmap to be used for the latched state. 
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[J virtual ITool BarButton& Supported On: 

setLatchedBitmap( unsigned long id); PM 

2 virtual IToolBarButton& Supported On: 

setLatchedBi tmap( const IResourceId& 1 atchedBi tmapld); PM 

0 virtual ITool BarButton& Supported On: 

setLatchedBitmap( const IBitmapHandle& handle); PM 


Canvas Support 

These members provide canvas support for tool bar buttons. 


setLayoutDistorted 

Indicates that changes have occurred in the window that will cause the layout of the 
window in a canvas to be updated. This implementation is used to optimize 
minimum size calculations. 


virtual IToolBarButton& 

setLayoutDistorted( unsigned long layoutAttributeOn, 
unsigned long 1ayoutAttributeOff); 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IToolBarButton 
objects because both the copy constructor and assignment operator are private functions. 


IToolBarButton 


ITool BarButton( unsigned long id. Supported On: 

IWindow* parent, PM 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Creates an IToolBarButton object from a control ID, parent and owner windows, 
rectangle, and style. 


The file icconst.h includes defines for bitmaps and text that you can use when 
constructing tool bar buttons for standard operations. 

IC_ID_OPEN 

IC_ID_SAVE 
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IC_ID_PRINT 

IC_ID_SETTINGS 

IC_ID_HELP 

IC_ID_CUT 

IC_ID_COPY 

IC_ID_PASTE 

IC_ID_COPYTO 

IC_ID_LOCATE 

IC_ID_BOLD 

IC_ID_ITALIC 

IC_ID_UNDERS CORE 


Tool Bar Buttons 
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Figure 11. Tool Bar Buttons 


Exceptions 

IlnvalidParameter The parent window pointer is invalid. 


"IToolBarButton 


virtual 

'IToolBarButton(); 


Supported On: 

PM 


Shredder Support 

Use these members to set and query whether the tool bar button can be dropped on a Workplace 
Shell shredder object. 


allowsDragDelete 

Returns true if the noDragDelete style is not set for the tool bar button. 
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Bool ean Supported On: 

al lowsDragDelete() const; PM 

disableDragDelete 

Sets the noDragDelete style for the tool bar button to prevent it from being dropped 
on a Workplace Shell shredder object. 


virtual IToolBarButton& Supported On: 

disableDragDelete(); PM 

enableDrag Delete 

Removes the noDragDelete style for the tool bar button to enable it to be dropped on 
a Workplace Shell shredder object. 


virtual IToolBarButton& 
enableDragDelete( Boolean enable = true); 


Supported On: 

PM 


Standard Format 

Use these members to set and query the values used for the standard formatting of tool bar 
buttons. Standard formatting controls the amount of area occupied by the bitmap (when visible) 
and the amount of area occupied by text (when visible). Standard formatting affects all of the 
tool bar buttons that have a style of IToolBarButton::standardFormat so that they have a 
consistent appearance. 

isStandardFormat 

Returns true if the button has a style of standardFormat. 

Boolean 

isStandardFormat() const; 

setStandardBitmapSize 

Sets the size of the area reserved for a bitmap for standard tool bar buttons when the 
bitmap is visible. The default size is 20 by 17. 

static void Supported On: 

setStandardBitmapSize( const ISize& newSize = ISize ( 20 , PM 

17)); 


Supported On: 

PM 
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setStandardTextLines 

Sets the number of lines to be displayed for standard tool bar buttons when text is 
visible. The default value is 1. 

static void Supported On: 

setStandardTextLines( unsigned long newLines = 1); PM 

setStandardTextWidth 

Sets the width to be used for standard tool bar buttons when text is visible. The 
default value is 50. 


static void Supported On: 

setStandardTextWidth( unsigned long newWidth = 50); PM 


standardBitmapSize 

Returns the size of the area reserved for a bitmap for a standard tool bar button when 
the button's bitmap is visible. The default size is 20 by 17. 

static ISize Supported On: 

standardBitmapSizeO; PM 


standardTextLines 

Returns the number of lines of text displayed for a standard tool bar button when the 
button's text is visible. The default value is 1. 

static unsigned long Supported On: 

standardTextLines(); PM 

standardT extWidth 

Returns the width of a standard tool bar button when the text is visible. The default 
value is 50. 

static unsigned long Supported On: 

standardTextWidth (); PM 


Styles 

Use these members to set and query IToolBarButton styles. You can use these styles with the 
styles defined by the following classes: 

IWindow (Vol. II) 

IControl (Vol. II) 
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IButton (Vol. II) 

ICustomButton (p. 260) 

convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

—Returns the default style. The default style is classDefaultStyle unless you have 
changed the style using setDefaultStyle. 

static Style Supported On: 

defaultStyle(); PM 


setDefaultStyle 

Sets the default style for all subsequent tool bar buttons. 

style Use the styles provided by IToolBarButton: :Style to specify the default 

style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM 


Transparency 

Use these members to control transparency when drawing the bitmap. A transparent color is 
used to indicate part of the bitmap that should not be drawn for the bitmap. For example, the 
area under the bitmap is not overpainted for areas of the bitmap that are set to the transparent 
color. These members do not actually modify the bitmap and are only used when the bitmap is 
drawn. 

Transparency allows a bitmap to display a nonrectangular image with the correct button 
background color. Transparency support is important for tool bar buttons because the 
background color used for the latched state can be different from the default background color. 

The default transparent color is IColor::pink (which has RGB values of red=255, green=0, 
blue=255). 
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clearDefauItTransparentColor 

Resets the default transparent color so that no color will be treated as transparent for 
subsequent buttons. 

static void 

clearDefaultTransparentColor(); 

defauItT ransparentColor 

Returns the current default transparent color. This color is initially set to IColor::pink 
(which has RGB values of Red=255, Green=0, Blue=255). 

static IColor 
defaultTransparentColor(); 

hasT ransparentColor 

Returns true if a transparent color has been set. 

virtual Boolean 
hasTransparentColor() const; 

isDefauItT ransparentColorSet 

Returns true if a default transparent color is set. 
static Boolean 

isDefaultTransparentColorSet(); 

resetT ransparentColor 

Resets the button so that no color is made transparent when drawing the bitmap. 

virtual ITool BarButton& Supported On: 

resetTransparentCol or(); PM 

setDefauItT ransparentColor 

Sets the default transparent color for all subsequent tool bar buttons. 

static void Supported On: 

setDefaul tTransparentCol or ( PM 

const IColor& aColor = IColor ( IColor::pink )); 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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setT ransparentColor 

Sets the color to be made transparent when drawing the bitmap. 


virtual IToolBarButton& 

setTransparentColor( const IColor& color = IColor::pink); 


Supported On: 

PM 


transparentColor 

Returns the current transparent color. 


virtual IColor 
transparentColor() const; 


Supported On: 

PM 


Views 

Use these members to set and query the current view of a tool bar button. 


isBitmap Visible 

Returns true if the bitmap is visible. 


Boolean Supported On: 

isBitmapVisible() const; PM 

—Returns true if the tool bar button text is visible. 


Boolean 

isTextVisible() const; 

.Sets the current view of the tool bar button. 

Note: The view of the tool bar button is changed to match the view of other tool bar 
buttons when it is added to a tool bar. 


virtual IToolBarButton& Supported On: 

setView( View buttonView); PM 

Returns the current view of the tool bar button. 


Supported On: 

PM 


Vi ew 

view() const; 


Supported On: 

PM 
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Inherited Public Functions 


ICustomButton 

backgroundColor 

isAutoLatchEnabled 

resetLatchedB ackgroundColor 

convertToGUIStyle 

isLatched 

resetLatchedForegroundColor 

defaultStyle 

i sLatchedB ackgroundColorHalftone 

setDefaultStyle 

disableAutoLatch 

isLatchingEnabled 

setLatchedB ackgroundColor 

disableLatching 

latch 

setLatchedForegroundColor 

enableAutoLatch 

latchedB ackgroundColor 

setUserData 

enableLatching 

latchedForegroundColor 

unlatch 


IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableNotification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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IToolBarButton 


Note: Members of IWindow (Vol. II) are not shown. 


Protected Functions 
Canvas Layout 

These members support canvas layout for tool bar buttons. 

calcMinimumSize 

Returns the recommended minimum size of this tool bar button control. The size is 
based on the bitmap, button text and current font. 

virtual ISize Supported On: 

calcMinimumSize() const; PM 


Inherited Protected Functions 


ICustomButton 

calcMinimumSize 




INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
Styles 

Use these members to set and query IToolBarButton styles. You can use these styles with the 
styles defined by the following classes: 

IWindow (Vol. II) 

IControl (Vol. II) 

IButton (Vol. II) 

ICustomButton (p. 260) 

bitmapAndTextVisible 

Displays the bitmap and tool bar button text. 
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Note: The view of the tool bar button is changed to match the view of other tool bar 
buttons when it is added to a tool bar. 

static const Style 
bitmapAndTextVisible; 

bitmapVisible 

Displays the bitmap. 

Note: The view of the tool bar button is changed to match the view of other tool bar 
buttons when it is added to a tool bar. 

static const Style 
bitmapVisible; 

classDefaultStyle 

Specifies the original default style for this class, which is 
IToolBarButton::bitmapVisible, IToolBarButton: :useIdForBitmap, 

IToolB arButton:: useldForText, IToolB arButton:: standardFormat, 
IButton::noPointerFocus, and IWindow::visible. 

static const Style 
classDefaultStyle; 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


noDragDelete 

Prevents the tool bar button from being dropped on a Workplace Shell shredder 
object. 

static const Style Supported On: 

noDragDelete; PM 


standardFormat 

Displays the tool bar button in a standard format for the application. All tool bar 
buttons that have this style are formatted the same (based on the standard bitmap size, 
text width, and number of text lines). 

static const Style 
standardFormat; 

- Displays the tool bar button text. 

Note: The view of the tool bar button is changed to match the view of other tool bar 
buttons when it is added to a tool bar. 


Supported On: 

PM 
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static const Style 
textVisible; 


Supported On: 

PM 


useldForBitmap 

Uses the window ID of the tool bar button as the ID for the bitmap resource when 
the button is constructed. 

If a bitmap resource cannot be found with the specified ID, the library tries to load a 
default bitmap for the tool bar button. If the default bitmap cannot be loaded, then 
the tool bar button does not use a bitmap. 

static const Style Supported On: 

useldForBitmap; PM 

—Uses the window ID of the tool bar button as the ID for the text resource when the 
button is constructed. 

If a string resource cannot be found with the specified ID, no text is set for the 
button. 

static const Style Supported On: 


useldForText; 



PM 

Inherited Public Data 

ICustomButton 

autoLatch 

classDefaultStyle 

latchable 


IButton 

buttonClickld 

noPointerFocus 



ITextControl 

textld 




IControl 

group 

tabStop 
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IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandtd 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IToolBarButton contains the following nested classes: 
IToolBarButton::Style (see page 1220) 


View { 

bitmapView, 
textView, 
bitmapAndTextView 
}; 


Use these enumerations to specify the view of the button. 

bitmapView 

Only the bitmap is visible. 

textView 

Only the text is visible. 

bitmap AndT ext Vie w 

Both the bitmap and text are visible. 
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IToolBarButton: :Style 



IToolBarButton::Style 


IBase 

IBitFlag 

IToolB arB utton:: S ty le 


_.None. 

—itbarbut.hpp 

The nested class IToolBarButton::Style provides a set of valid styles for the static 
member functions of the class IToolBarButton. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IT oolBarContainer 



IToolBarContainer 


IBase 
IVBase 
INotifier 
IWindow 
IControl 
ICanvas 
ISetCanvas 
IToolB arContainer 


_.None. 

__itbarcnr.hpp 


Member Page 

Constructor 1222 

classDefaultStyle 1225 

convertToGUIStyle 1223 

defaultStyle 1223 

frameToolB arContainer 1222 


Member 

Page 

location 

1222 

setDefaultStyle 

1223 

setLayoutDistorted 

1221 

setLocation 

1222 

“IToolBarContainer 

1222 


The IToolBarContainer class creates and manages a tool bar container for a frame 
window. Objects of this class are created by IToolBar objects when calling the 
IToolBar::createToolBarContainer function. 


Public Functions 
Canvas Layout 

These members support canvas layout. 


setLayoutDistorted 

Treats a minimum size change for a child window like a layout change so that the 
container resizes as new windows are added or removed from tool bars. 


virtual IToolBarContainer& 
setLayoutDistorted( unsigned long layoutAttributeOn, 
unsigned long 1ayoutAttributeOff); 


Supported On: 

PM 
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IT oolBarContainer 


Constructors 

You can construct and destruct objects of the this class. You cannot copy or assign 
IToolBarContainer objects because both the copy constructor and assignment operator are private 
functions. 


IToolBarContainer 

IToolBarContainer( unsigned long identifier. Supported On: 

IFrameWindow* parentAndOwner, PM 

IFrameWindow::Location location, 

const Style& style = defaultStyle ( )); 

Creates an IToolBarContainer object by providing a window ID, frame window, 
location, and style. 

"IToolBarContainer 


virtual 

'I ToolBarContainer(); 


Supported On: 

PM 


Frame Location 

Use these members to set and query the tool bar container's location. 


frameToolBarContainer 

Returns the tool bar container for the specified frame and location. 


static IToolBarContainer* 
frameToolBarContainer( IFrameWindow* frame, 

IFrameWindow::Location frameLocation); 


Supported On: 

PM 


Returns the current frame window location of the tool bar container. 


IFrameWindow: location Supported On: 

location() const; PM 

_Sets a new frame window location for the tool bar container. 


virtual IToolBarContainer& 
setLocation( IFrameWindow::Location location); 


Supported On: 

PM 
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Styles 

Use these members to set and query IToolBarContainer styles. You can use these styles with the 
styles defined by the following nested classes: 

IWindow Styles (Vol. II) 

ICanvas Styles (p. 34) 

ISetCanvas Styles (p. 1147) 

convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

_. Returns the default style. The default style is classDefaultStyle unless you have 
changed the style using setDefaultStyle. 

static Style Supported On: 

defaultStyle(); PM 


setDefaultStyle 

Sets the default style for all subsequent tool bar containers. 

style Use the styles provided by IToolBarContainer::Style to specify the default 

style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM 


Inherited Public Functions 


ISetCanvas 

alignment 

packType 

setLay outDi storted 

convertToGUIStyle 

pad 

setMargin 

deckCount 

position 

setPackType 

deckOrientation 

setAlignment 

setPad 
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ISetCanvas 

defaultStyle 

setDeckCount 

setText 

groupPad 

setDeckOrientation 

size 

margin 

setDefaultStyle 

text 

moveSizeTo 

setGroupPad 

topHandle 


ICanvas 

backgroundColor 

defaultStyle 

origDefaultButtonHandle 

convertToGUIStyle 

isTabStop 

setDefaultStyle 

defaultPushButton 

matchForMnemonic 

setLayoutDistorted 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Functions 


ISetCanvas 

expandForText 

layout 



ICanvas 

areChildrenReversed 

layout 

registerCallbacks 

calcMinimumSize 

layoutSize 

setLay outSize 
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ICanvas 

fixupChildren 

passEventT oOwner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Public Data 
Styles 

Use these members to set and query IToolBarContainer styles. You can use these styles with the 
styles defined by the following nested classes: 

IWindow Styles (Vol. II) 

ICanvas Styles (p. 34) 

ISetCanvas Styles (p. 1147) 


classDefaultStyle 

Specifies the original default style for this class, which is IWindow:ivisible. 

static const Style Supported On: 

classDefaultStyle; PM 


Inherited Public Data 


ISetCanvas 

border 

deekOrientationld 

packExpanded 

bottomAlign 

decksByGroup 

packTight 

center Align 

horizontalDeeks 

rightAlign 

centerV erticalAlign 

leftAlign 

textld 

classDefaultStyle 

packEven 

topAlign 


ICanvas 

classDefaultStyle 
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IWindow 

activeColorld 

disabiedBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IToolBarContainer contains the following nested classes: 
IToolBarContainer::Style (see page 1227) 
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IToolBarContainer::Style 


IBase 

IBitFlag 

IToolBarContainer: :Style 


_.None. 

_ itbarcnr.hpp 

The nested class IToolBarContainer::Style provides a set of valid styles for the static 
member functions of the class IToolBarContainer. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IT oolBarF rameWindow 



IToolBarFrameWindow 


IBase 
IVBase 
INotifier 
IWindow 
IFrame Window 
IToolB arFrame W indo w 


_.None. 

__itbarfrm.hpp 


Member 

Page 

Member 

Page 

Constructor 

1229 

titleText 

1229 

setTitleText 

1229 

"IToolBarFrameWindow 

1229 


The IToolBarFrameWindow class is used to contain floating tool bars. 

IToolBarFrameWindows are created when a user constructs a tool bar with a location 
of floating or calls IToolBar::setLocation with a value of IToolBar::floating. 

IToolBarFrameWindows are visually distinct from other frame windows in that the 
title bar height of IToolBarFrameWindows is smaller than other frame windows. In 
addition, there are two buttons that appear where the frame window's minimize and 
maximize buttons normally are. 

The left button is a toggle button that allows you to pin or attach a tool bar frame 
window to its owning frame window. This has the effect that the tool bar stays in the 
same location relative to its owner when the owner is moved. 

The right button allows you to expand and collapse the tool bar contained in the tool 
bar frame window. This allows you to shrink the tool bar to recover screen area 
when you are not actively using the tool bar and later expand the tool bar to show all 
tool bar controls. 
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IT oolBarF rameWindow 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IToolBarFrameWindow 

IToolBarFrameWindow( unsigned long windowld. Supported On: 

IFrameWindow* owner); PM 

Creates and IToolBarFrameWindow object with the specified window ID and the 
specified frame window as owner. 

"IToolBarFrameWindow 


virtual Supported On: 

'ITool BarFrameWindow(); PM 


Title Text 

Use these members to set or query the title text of an IToolBarFloatingFrame object. 
-. Sets the text of the tool bar frame title bar. 


Q virtual IToolBarFrameWindow& Supported On: 

setTitleText( const char* text); PM 


§ virtual IToolBarFrameWindow& Supported On: 

setTitleText( const IResourceId& text); PM 

Returns the text of the tool bar frame title bar. 


IString 

titleText() const; 


Supported On: 

PM 


Inherited Public Functions 


IFrameWindow 

addExtension 

isFlashing 

setBorderWidth 

addToWindowList 

isMaximized 

setClient 
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IF rameWindow 

backgroundColor 

isMinimized 

setDefaultOrdering 

beginFlashing 

isModal 

setDefaultStyle 

borderHeight 

maximize 

setDestroyOnClose 

borderSize 

maximizeRect 

setExtensionSize 

borderWidth 

minimize 

setlcon 

client 

minimizeRect 

setLayoutDistorted 

clientHandle 

mousePointer 

setMousePointer 

clientRectFor 

moveSizeToClient 

setRestoreRect 

close 

nextShellRect 

setResult 

convertToGUIStyle 

notifyOwner 

setToolBarList 

defaultOrdering 

removeExtension 

shareParentDBCSStatus 

defaultStyle 

remo veFromW indo wList 

show 

disabledBackgroundColor 

resetBackgroundColor 

showModally 

dismiss 

resetDisabledBackgroundColor 

start 

enableNotification 

restore 

toolBarList 

endFlashing 

restoreRect 

topHandle 

frameRectFor 

result 

update 

handleFor 

setBorderHeight 

useExtensionMinimumSize 

icon 

setBorderSize 

usesDialogBackground 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 
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Inherited Protected Functions 


IFrameWindow 

addDefaultHandler 

findExtensions 

registerFrameClass 

attachClient 

initialize 

removeDefaultHandler 

create 

isFrameWindow 

setExtensions 

extensions 

isRelatedHandle 

tryToLoadDialog 

findExtension 

registerCallbacks 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Public Data 


IFrameWindow 

accelerator 

deferCreation 

minimized 

activateld 

dialogBackground 

minimizedlcon 

alignNoAdjust 

dialogBorder 

noMoveWithOwner 

animated 

hideButton 

shellPosition 

appDBCSStatus 

horizontalScroll 

sizingBorder 

border 

maximizeButton 

systemMenu 

classDefaultStyle 

maximized 

systemModal 

closeld 

menuBar 

titleBar 

deactivateld 

minimizeButton 

verticalScroll 


IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoIorld 

systemCommandld 

deleteld 

hiliteForegroundCoIorld 

visible 
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Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 
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ITransform Matrix 


IBase 

ITransformMatrix 


..None. 


_ itrnsfrm.hpp 


Member 

Page 

Member 

Page 

Constructor 

1234 

rotateBy 

1237 

asMATRIXLF 

1235 

scaleBy 

1237 

element 11 

1235 

setElementl 1 

1236 

element 12 

1235 

setElementl2 

1236 

element21 

1235 

setElement21 

1236 

element22 

1236 

setElement22 

1236 

element31 

1236 

setElement31 

1237 

element32 

1236 

setElement32 

1237 

operator != 

1233 

setToIdentity 

1237 

operator = 

1235 

translateBy 

1238 

operator == 

1233 

'ITransformMatrix 

1235 


The ITransformMatrix class is used to represent a 3x3 transformation matrix. 


You can use ITransformMatrix objects to quickly construct transformation matrixes 
for use with IGraphic::setTransformMatrix or with the native graphic programming 
interface. 


Public Functions 
Comparisons 

Use these members to compare two ITransformMatrix objects. 
_ Returns true if the transform matrixes are not equal. 


IBase: :Boolean Supported On: 

operator ! = ( PM 

const ITransformMatrix& transformMatrix) const; 

..Returns true if the transform matrixes are equal. 
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IBase::Boolean 
operator ==( 

const ITransformMatrix& transformMatrix) const; 


Supported On: 

PM 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 


ITransformMatrix 


ITransformMatrix(); 


Supported On: 

PM 


Use the default construct to create a ITransformMatrix object that is initialized to the 
identity matrix. 


ITransformMatrix( double elementll, Supported On: 

double elementl2, PM 

double element21, 
double element22, 
long element31, 

1ong element32); 

Use this function to construct a ITransformMatrix object from six of the nine 
elements in the matrix. The elements at 1,3, 2,3, and 3,3 default to 0, 0, and 1 
respectively. 


elementll 

elementH 

elementH 

element22 

element31 

element32 


Matrix element 1,1 (Used to scale, rotate, and reflect). 
Matrix element 1,2 (Used to scale and rotate). 

Matrix element 2,1 (Used to scale and rotate). 

Matrix element 2,2 (Used to scale, rotate, and reflect). 
Matrix element 3,1 (Used to translate). 

Matrix element 3,2 (Used to translate). 


Q ITransformMatrix( const struct _MATRIXLF& matrixlf); Supported On: 

PM 

Use this function to construct a ITransformMatrix object from a PM Toolkit 
MATRIXLF structure. 

matrixlf Presentation Manager MATRIXLF structure. 
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@ ITransformMatrix( 

const ITransformMatrix& transformMatnx); 

Use this function to construct a ITransformMatrix object front another 
ITransformMatrix object. 

transformMatrix A ITransformMatrix object. 

.Use this function to assign a ITransformMatrix object to another ITransformMatrix 

object. 

ITransformMatrix& 

operator =( const ITransformMatrix& matrix); 

ITransformMatrix 

"ITransformMatrixQ; Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Matrix Elements 

Use these members to set and query the elements of the transform matrix. In addition, there is a 
member that resets the transform matrix to the identity matrix (setToIdentity) and one that returns 
the transform matrix as an environment-specific structure (asMATRIXLF in the OS/2 operating 
system). 


_ Renders the matrix as an OS/2 Developers Toolkit MATRIXLF structure. 

struct _MATRIXLF Supported On: 

asMATRIXLF() const; PM 

.Returns the value for the matrix element 1,1. 

double 

elementll() const; 

.Returns the value for the matrix element 1,2. 

double Supported On: 

elementl2() const; PM 

.Returns the value for the matrix element 2,1. 


Supported On: 

PM 
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setElementll 


setElement12 


setElement21 


setElement22 


double 

element21() const; 

-Returns the value for the matrix element 2,2. 


double 

element22() const; 

.Returns the value for the matrix element 3,1. 


long 

element31() const; 

-Returns the value for the matrix element 3,2. 


long 

element32() const; 


Sets the value for element 1,1 in the transformation matrix. 


ITransformMatrix& 
setElementll( double value); 


Sets the value for element 1,2 in the transformation matrix. 


ITransformMatrix& 
setElementl2( double value); 


Sets the value for element 2,2 in the transformation matrix. 


ITransformMatrix& 
setElement21 ( double value); 


Sets the value for element 2,2 in the transformation matrix. 


ITransformMatrix& 
setElement22( double value); 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 


Supported On: 

PM 
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setElement31 

Sets the value for element 3,1 in the transformation matrix. 

ITransformMatrix& Supported On: 

setElement31 ( long value); PM 


setElement32 

Sets the value for element 3,2 in the transformation matrix. 


ITransformMatrix& Supported On: 

setElement32( long value); PM 

-.Resets the transformation matrix to the identity matrix. 


ITransformMatrix& Supported On: 

setToIdentity(); PM 

Scale, Rotate, and Translate 

Use these members to apply a transform to a matrix. 

-Applies a rotation transform to the matrix. A rotation transform rotates graphic 
objects. The last argument specifies the point around which the rotation occurs. 


ITransformMatrix& 
rotateBy( double angle, 

const IPoint& point = I Point ( 0 , 0 )); 


Supported On: 

PM 


Exceptions 

IAccessError Could not perform the rotate operation. Make sure you not attempting to 

access the object concurrently from another thread. 


..Applies a scaling transform to the matrix. A scaling transform reduces or increases 
the size of graphic objects. The last argument specifies the point around which the 
scale occurs. 


ITransformMatrix& Supported On: 

scaleBy( double xScale, PM 

double yScale, 

const IPoint& point = IPoint (0,0)); 


Exceptions 

IAccessError Could not perform the scale operation. Make sure you not attempting to 

access the object concurrently from another thread. 
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—Applies a translation transform to the matrix. A translation transform moves 
graphic objects. 


ITransformMatrix& 

translateBy( const IPoint& point); 


Supported On: 

PM 


Exceptions 

IAccessError Could not perform the translate operation. Make sure you not attempting 

to access the object concurrently from another thread. 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IViewPort 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ICanvas 

IViewPort 


_.None. 

__ivport.hpp 


Member 

Page 

Member 

Page 

Constructor 

1241 

scrollViewHorizontallyTo 

1243 

alwaysHorizontalScrollBar 

1248 

scroll V iew V erticallyT o 

1244 

alwaysVerticalScrollBar 

1248 

setDefaultStyle 

1243 

asNeededHorizontalScrollBar 

1248 

setLayoutDistorted 

1242 

asNeededVerticalScrollBar 

1249 

setT opLeft V ie wPoint 

1246 

calcMinimumSize 

1246 

setupScrollBars 

1247 

classDefaultStyle 

1249 

s et V ie w W indo w S ize 

1244 

convertToGUIStyle 

1243 

topLeft V ie wPoint 

1247 

defaultStyle 

1243 

verticalScrollBar 

1241 

horizontalScrollBar 

1240 

view Window 

1244 

layout 

1246 

viewWindowDrawRectangle 

1244 

noHorizontalScrollBar 

1249 

viewWindowSize 

1245 

noVerticalScrollBar 

1249 

viewWindowSizeld 

1248 

no V ie w W indo wFill 

1249 

“IViewPort 

1242 

position V iewW indo w 

1246 




Objects of the IViewPort class provide scrolling support for another window. The 
window being scrolled is termed the view window. Typically, the view window does 
not readily support resizing. Because of this, you must support scrolling so users can 
scroll the view window to see clipped information. 

View window candidates include the following classes: 

ICanvas (p. 27) 

ISetCanvas (p. 1138) 

INotebook (p. 1066) 

IContainerControl (p. 163) 
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You specify the view window by making it a child window of the view port. A view 
port only supports one view window. The view port changes the parent window of 
the view window to a scrollable rectangular window to properly clip the child 
window. 

The IViewPort object optionally includes horizontal and vertical scroll bars. You can 
specify scroll bars that are the following: 

• Always visible 

• Never visible 

• Visible only if the size of the view window is larger than the size of the view 
port window 

If the view port has nothing to scroll because the view window is entirely visible, 
the scroll bars are hidden. 

Logical sizes specified through IViewPort::setViewWindowSize are limited to 
0x3FFF0000. If you do not call setViewWindowSize, the size of a view window is 
limited to 32 K. If the view window has no size and does not use a logical size, 
IViewPort sizes the view window to its minimum size. 

Note: Only one window can be a child of the IViewPort window. If you try to give 
the view port control more than one child, an IlnvalidRequest exception is 
thrown. 

ee The AIX release of the User Interface Class Library does not support the style 

combination of one scroll bar displayed as needed and the other scroll bar always 
displayed. If this combination of styles is used, both scroll bars are always displayed. 
Motif supports all other combinations for displaying the view port scroll bars. 

Note: Previous versions of this class created each scroll bar with a 1-based range. 

The scroll bar ranges are now 0-based so that the interface is consistent with 
scrollViewHorizontallyTo (p. 1243) and scrollViewVerticallyTo (p. 1244). 


Public Functions 
Child Scroll Bars 

Use these members to access the scroll bar windows created by the IViewPort window. 

horizontalScrollBar 

Returns the address of the horizontal scroll bar. 


IScrol1 Bar* 

horizontal Scroll Bar() const; 


Supported On: 

PM. Motif 
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verticalScrollBar 

Returns the address of the vertical scroll bar. 


IScrol1 Bar* 

verticalScrol1Bar() const; 


Supported On: 

PM, Motif 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IViewPort 
objects because both the copy constructor and assignment operator are private functions. 

IViewPort 


IViewPort( unsigned long windowldentifier, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial Size = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

windowld Window identifier of the canvas you construct. 

Note: For OS/2, this value should be limited to the range 0 through 
65535. 

It is recommended that you: 

• Give unique identifiers to all windows in the same frame window. In 
the same window means that the frame window is the first frame in 
their parent window chain. 

• Give the client window a window ID of FID_CLIENT (0x8008). 

• Do not use the other FID_xxx values. 

The OS/2 version of IViewPort class reserves the following window IDs 
for child windows that it creates: 

IC_VIEWPORT_VERTSCROLLBAR 

Vertical scroll bar. 

IC_VIEWPORT_HORZSCROLLBAR 

Horizontal scroll bar. 

IC_VIEWPORT_VIEWRECTANGLE 

Scroll rectangle window. The window within which the 
application window is scrolled. IViewPort changes the parent 
of the view window to this window. 


Supported On: 

PM, Motif 
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parent The parent window of the canvas you construct. You must specify a 

parent window. This constructor throws an IlnvalidParameter exception 
if you pass an IWindow* of 0. 

The parent window is primarily used for visible relationships. 

owner Owner window of the canvas you construct. 

Note: In OS/2, the owner window is primarily used for routing 

notification events and unprocessed messages. OS/2 also uses the 
owner window chain to inherit colors. 

In Motif, the owner window is only used for routing unprocessed 
messages. There is no concept of an owner in Motif. 

initial (Optional) The initial position and size of the canvas you construct. The 
initial position is the lower-left corner of the canvas relative to the 
lower-left comer of the parent window. 

style (Optional) The window's characteristics. These can be a combination of 

the IViewPort::Style and the IWindow::Style. 

Exceptions 

IlnvalidParameter style contains an invalid combination of styles, style cannot contain more 

than one horizontal scroll bar style (IViewPort::alwaysHorizontalScrollBar, 
IViewPort::asNeededHorizontalScrollBar, and 

IViewPort::noHorizontalScrollBar), or more than one vertical scroll bar 
style (IViewPort::alwaysVerticalScrollBar, 
IViewPort::asNeededVerticalScrollBar, and 
IViewPort::noVerticalScrollBar). 

"IViewPort 

virtual 

'IViewPort() ; 

Layout Support 

Layout members determine how this class sizes and positions its child windows or how this 
window will be laid out on another canvas. 

setLayoutDistorted 

Processes a size change as a layout change. 

virtual IViewPort& Supported On: 

setLayoutDistorted( unsigned long layoutAttributeOn, PM. Motif 

unsigned long 1ayoutAttributeOff); 


Supported On: 

PM. Motif 
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Styles 

Use these members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 
You can use these styles with the styles defined by the following nested classes: 

ICanvas::Styles (p. 34) 

IWindow:: Styles (Vol. II) 

Once you have constructed an IViewPort object, you can use IViewPort, ICanvas, and IWindow 
member functions to query and change its style. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

_. Returns the default style. The default style is classDefaultStyle (p. 1249) unless you 
change the style using setDefaultStyle (p. 1243). 

static Style Supported On: 

defaul tStyle(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent view ports. 

static void Supported On: 

setDefaultStyle( const Style& style); PM, Motif 

style A combination of IViewPort: :Style (p. 1248), ICanvas::Style (p. 34), and 

IWindow::Style (Vol. II) objects. 


View Window 

Use these members to change the appearance of the view window in the view port. 

scroll ViewHorizontallyT o 

Scrolls the view window horizontally. 
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virtual IViewPort& Supported On: 

scrol 1 ViewHorizontallyTo( unsigned long leftOffset); PM, Motif 

leftOffset The 0-based offset from the left edge of the view window to scroll to the 
left edge of the view port. 


scroll ViewVerticallyT o 

Scrolls the view window vertically. 


virtual IViewPort& Supported On: 

scrol 1 ViewVertical 1 yTo( unsigned long topOffset); PM, Motif 

topOffset The 0-based offset from the top edge of the view window to scroll to the 
top edge of the view port. 


setViewWindowSize 

Changes the logical size of the window being scrolled. The logical size does not 
have to match the real size of the window. 

If you call this function, you will manage the appearance of the view window. 
IViewPort processes the position and size of the scroll boxes of its scroll bars, but 
you are responsible for changing the position or repainting the view window to give 
the appearance of scrolling. 

virtual IViewPort& 

setViewWindowSize( const ISize& size); 
size New logical size of the view window. 

-..Returns the handle of the window bounded by the view port. If more than one 
child of the view port is found, an exception is thrown. The parent of the view 
window is changed to the scrollable rectangular window so that the view window is 
properly clipped. 

virtual IWindowHandle 
viewWindow(); 


Exceptions 

IlnvalidRequest The view port has found more than one view window. A view port can 

have only one child window. 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


viewWindowDrawRectangle 

Returns the area of the view window that is currently visible in the view port. 
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virtual IRectangle 
viewWindowDrawRectangle() const; 


Supported On: 

PM, Motif 


viewWindowSize 

Returns the logical size of the window being scrolled. If you have not called 
IViewPort::setViewWindowSize (p. 1244) to set a logical size, the real size of the 
view window is returned. 


virtual ISize 
viewWindowSize() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


ICanvas 

backgroundColor 

defaultStyle 

origDefaultB uttonHandle 

convertToGUIStyle 

isTabStop 

setDefaultStyle 

defaultPushButton 

matchForMnemonic 

setLay outDi storted 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (Vol. II) are not shown. 
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Protected Functions 
Layout Support 

Layout members determine how this class sizes and positions its child windows or how this 
window will be laid out on another canvas. 

calcMinimumSize 

Returns the recommended minimum size for this IViewPort object. The size is based 
on the minimum size of the vertical and horizontal scroll bars. 


virtual ISize Supported On: 

calcMinimumSize() const; PM. Motif 

Positions the scroll bars, scroll rectangle window, and view window. 


virtual IViewPort& 
layout(); 


Supported On: 

PM. Motif 


View Window 

Use these members to change the appearance of the view window in the view port. 

positionViewWindow 

Positions the view window within the view rectangle. 

virtual IViewPort& Supported On: 

positionViewWindow( const IWindowHandle& viewWindow, PM. Motif 

const IRectangle& viewRectangle); 

viewWindow 

Window handle of the view window. 
viewRectangle 

Rectangle whose size defines how much of the view window can display 
in the view window. You can query the top-left comer of the view 
window that is visible in the rectangle using 

IViewPort::topLeftViewPoint. positionViewWindow is called by the 
IViewPort::scrollViewHorizontallyTo, scrollViewVerticallyTo, and layout 
member functions. 


setTopLeft Viewpoint 

Sets the view window coordinate that displays in the upper-left corner of the view 
rectangle. 
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virtual IViewPort& Supported On: 

setTopLeftViewPoint( const IPoint& topLeft); PM, Motif 

topLeft The coordinate in the view window that the IViewPort considers visible 
in the upper-left corner of the view port. To scroll the view window, call 
IViewPort::scrollViewHorizontallyTo or scrollViewVerticallyTo instead 
of setTopLeftViewPoint. This function does not update the scroll bars. 


setupScrollBars 

Sizes, shows, or hides scroll bars for the view port window, as appropriate. This 
function also positions and sizes the scroll rectangle window that bounds the view 
window. IViewPort calls this function before calling positionViewWindow (p. 1246). 

virtual IViewPort& Supported On: 

setupScrol 1 Bars (); PM, Motif 


topLeft Viewpoint 

Returns the view window coordinate that displays in the upper-left corner of the view 
rectangle. 


I Poi nt Supported On: 

topLeftViewPoint() const; PM, Motif 


Inherited Protected Functions 


ICanvas 

areChildrenReversed 

layout 

registerCallbacks 

calcMinimumSize 

layoutSize 

setLay outSize 

fixupChildren 

passEventT oOwner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (Vol. II) are not shown. 
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Public Data 

Notification Members 

These members allow observers to process changes to the window. 

viewWindowSizeld 

Notification identifier provided to observers when the logical size of the view port's 
view window changes. IViewPort provides a pointer to an ISize object for the new 
size in the eventData field of the INotificationEvent. 

static INotificationld const 
viewWindowSizeld; 

Styles 

Use these members to customize a window at the time you construct it. Most styles have 
equivalent member functions, which allow you to similarly modify a window after creating it. 
You can use these styles with the styles defined by the following nested classes: 

ICanvas::Styles (p. 34) 

IWindow::Styles (Vol. II) 

Once you have constructed an IViewPort object, you can use IViewPort, ICanvas, and IWindow 
member functions to query and change its style. 

alwaysHorizontalScroliBar 

Specifies that the view port never removes the horizontal scroll bar. 

static const Style 
alwaysHorizontalScrol1 Bar; 

alwaysVerticalScrollBar 

Specifies that the view port never removes the vertical scroll bar. 

static const Style 
al waysVerticalScrol1 Bar; 

asNeededHorizontalScroliBar 

Specifies that the view port removes the horizontal scroll bar when the entire width of 
the view window is visible and there is no data to scroll horizontally. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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static const Style Supported On: 

asNeededHorizontalScrol 1 Bar; PM, Motif 

asNeededVerticalScrollBar 

Specifies that the view port removes the vertical scroll bar when the entire height of 
the view window is visible and there is no data to scroll vertically. 


static const Style 
asNeededVerticalScrol1 Bar; 


Supported On: 

PM, Motif 


classDefaultStyle 

Specifies the original default style for this class, which is 

IViewPort::asNeededHorizontalScrollBar I IViewPort::asNeededVerticalScrollBar I 
IWindow:: visible. 


static const Style Supported On: 

classDefaultStyle; PM, Motif 

noHorizontalScrollBar 

Specifies that the view port never shows the horizontal scroll bar. 

static const Style 
noHorizontalScrol1 Bar; 

noVerticalScrollBar 

Specifies that the view port never shows the vertical scroll bar. 

static const Style 
noVertical Scrol1 Bar; 

noViewWindowFill 

Specifies that the view port does not paint the portion of the view rectangle occupied 
by the view window. 

Note: If you know that the view window paints its entire rectangle, specify this style 
to optimize overall painting. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


static const Style 
noVi ewWindowFi11; 


Supported On: 

PM, Motif 
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Inherited Public Data 


ICanvas 

classDefaultStyle 




IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

dipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (Vol. II) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IViewPort contains the following nested classes: 
IViewPort::Style (see page 1251) 
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IViewPort:: Style 



IViewPort::Style 


IBase 

IBitFlag 

IViewPort::Style 


_.None. 

_.ivport.hpp 

The nested class IViewPort::Style provides a valid set of view port styles for the 
defaultStyle and setDefaultStyle functions, and for the constructor of the class 
IViewPort (p. 1239). 

ee The AIX release of the User Interface Class Library does not support having one 
scroll bar created with the style asNeeded and the other scroll bar with the style 
always. If you use this combination of styles, both scroll bars are always displayed. 
All other combinations of displaying scroll bars are supported. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

set Value 
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IViewPort:: Style 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Summary of Changes 


The User Interface Class Library version 3.0 contains the following changes and 
enhancements: 

• New and enhanced classes 

• New and enhanced functions 

• New styles 

For late-breaking news, refer to the README file shipped with the product. 

Some header files have been optimized to include only the headers it requires. 
Therefore, if you obtain compiler errors stating that a class was not found, you should 
include the necessary header file. 


New and Enhanced Classes 

The following classes are new: 

• Bi-directional Support 

IWindow::BidiSettings 

• Control Classes 

IMouseEvent 

IMouseHandler 

IMousePointerEvent 

IMousePointerHandler 

• Multimedia Classes 

IMM24FramesPerSecondTime 

IMM25FramesPerSecondTime 

IMM30FramesPerSecondTime 

IMMAmpMixer 

IMMAudioBuffer 

IMMAudioCD 

IMMAudioCDContents 

IMMCDDA 

IMMCDXA 

IMMConfigurableAudio 

IMMCuePointEvent 

IMMDevice 
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IMMDeviceEvent 

IMMDeviceHandler 

IMMDigital V ideo 

IMMErrorlnfo 

IMMFileMedia 

IMMHourMinSecFrameTime 

IMMHourMinSecTime 

IMMMasterAudio 

IMMMillisecondTime 

IMMMinSecFrameTime 

IMMN otify Event 

IMMPassDeviceEvent 

IMMPlayableDevice 

IMMPlayerPanel 

IMMPlayerPanelHandler 

IMMPositionChangeEvent 

IMMRecordable 

IMMRemoveableMedia 

IMMSequencer 

IMMSpeed 

IMMTime 

IMMTrackMinSecFrameTime 
IMMW ave Audio 

• Notification Support Classes 

IButtonNotifyHandler 

ICircularSliderNotifyHandler 

IComboBoxNotifyHandler 

IContainerControlNotifyHandler 

IEntryFieldNotifyHandler 

IFrameWindowNotifyHandler 

IListBoxNotifyHandler 

IMenuNotifyHandler 

IMultiLineEditNotifyHandler 

INotebookNotifyHandler 

INotificationEvent 

INotifier 

INumericSpinButtonNotifyHandler 

IObserver 

IObserverList 

IS crollB arNotifyHandler 

ISettingButtonNotifyHandler 

IStandardNotifier 

ITextControlNotifyHandler 
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ITextSpinButtonNotifyHandler 

ITitleNotifyHandler 

IWindowNotifyHandler 

• Tool Bar Support Classes 

ICustomButton 

ICustomButtonDrawEvent 

ICustomButtonDrawHandler 

IToolBar 

IToolBarButton 

IToolBarContainer 

IToolBarFrameWindow 

• 2-D Graphics Support Classes 

IGArc 

IGBitmap 

IGChord 

IGEllipse 

IGLine 

IGList 

IGList::Cursor 

IGPie 

IGPolygon 

IGPolyline 

IGRectangle 

IGRegion 

IGString 

IGraphic 

IGraphicBundle 

IGraphic Context 

IG3PointArc 

IPointArray 

ITransformMatrix 

• Fly Over Help Classes 

IFlyOverHelpHandler 

IFlyText 

• String Parsing Support Class 

IStringParser 

• Timer Support Classes 

ITimer 

ITimer:: Cursor 
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ITimerFn 
ITimerMemberFn 
IT imerMemberF nO 

• Spin Button Classes 

IBaseSpinButton 
INumericSpinButton 
ITextSpinButton 
ITextSpinButton:: Cursor 

• ListBox Classes 

IBaseListBox 

ICollectionViewListBox 

IListBoxSizeltemEvent 

• ComboBox Classes 

IBaseComboBox 

ICollectionViewComboBox 

• String Generation Support Classes 

IS tringGenerator 
IS tringGeneratorFn 
IS tringGeneratorMemberFn 
IS tringGeneratorRefMemberFn 

• ClipBoard Support Classes 

IClipBoard 

IClipBoardHandler 

• Window Coordinate Mapping Support Classes 

ICoordinateSystem 

• Animated Button Support Class 

IAnimatedButton 

• Additional Canvas Classes 

IDrawingCanvas 

• Additional Container Class 

ICnr Allocator 

• Additional Direct Manipulation Classes 

IDMMenuItem 

IDMTBarButtonltem 

IDMToolBarltem 
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IDMT argetEvent 

• Additional Help Classes 

IHelpHyperlinkEvent 

• Additional Slider Classes 

ICircularSlider 

ISliderArmHandler 


New and Enhanced Member Functions 

The following classes have new member functions: 


Class Name 

Member Function 

I3StateCheckBox 

convertToGUIStyle 

IAccelerator 

reset 

IBitmapControl 

convertToGUIStyle 

IBuffer 

includesMBCS 

isMBCS 

isValidMBCS 

IButton 

backgroundColor 

disabledForegroundColor 

enableNotification 

foregroundColor 

hiliteB ackgroundColor 

hiliteForegroundColor 

ICanvas 

backgroundColor 

convertToGUIStyle 

ICheckBox 

convertToGUIStyle 

IComboBox 

convertToGUIStyle 
enableNotification 
layout Adjustment 
minimumRows 

setMinimumRows 

visibleRectangle 

enum ControlType dropDownList 

IContainerColumn 

isHeadingWriteable 

isWriteable 

IContainerObj ect 

isWriteable 


operator new 

ICurrentThread 

isGUIInitialized 

initializeGUI 

terminateGUI 
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Class Name 

Member Function 

IDBCSBuffer 

charLength 

includesMBCS 

isMBCS 

isValidMBCS 

isSBC 

maxCharLength 

prevCharLength 

IDM 

enum RenderCompletion targetSuccessful 
enum RenderCompletion targetFailed 

IDMHandler 

isContainerControl 

IDMImage 

defaults tyle 
setDefaultStyle 

IDMItem 

isT argetThe S ource 
tokenForWPS Object 

IDMOperation 

drag W aslnterrupted 
setDragResult 
setContainerRefreshOff 
setContainerRefreshOn 

IDMSourceOperation 

operation 

setStackingPercentage 

stackingPercentage 

IEntryField 

backgroundColor 

convertToGUIStyle 

cursorPosition 

enableNotification 

foregroundColor 

isWriteable 

removeAll 
selectedT extLength 
setChangedFlag 
setCursorPosition 

IEvent 

controlHandle 

controlWindow 

dispatchingWindow 

operator = 

setControlHandle 

setDispatchingHandle 

setHandle 

IEventData 

asLong 

IFileDialog 

convertToGUIStyle 
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Class Name 

Member Function 

IFileDialog:: Settings 

fileName 

initialDrive 

initialFileType 

isDialogTemplateSet 

isOpenDialog 

isPositionSet 

okButtonText 

position 

title 

IFileDialogHandler 

handleEventsFor 

stopHandlingEventsFor 

IFont 

operator = 

enum Direction leftToRight 
enum Direction topToBottom 
enum Direction rightToLeft 
enum Direction bottomToTop 

IFontDialog 

defaultStyle 

setDefaultStyle 

convertToGUIStyle 

IFontDialog: :Settings 

setFont 

IFrameExtension 

useMinimumSize 

IFrameHandler 

positionExtensions 

IFrameWindow 

backgroundColor 

convertToGUIStyle 

di sabledB ackgroundColor 

enableNotification 

enum FrameSource dialogResource 

enum FrameSource noDialogResource 

enum FrameSource tryDialogResource 

isAnExtension 

mousePointer 

resetB ackgroundColor 

resetDisabledB ackgroundColor 

setLayoutDistorted 

setMousePointer 

setToolBarList 

toolBarList 

useExtensionMinimumSize 

IGraphicPushButton 

convertToGUIStyle 

marginSize 

setMarginSize 

IGroupBox 

convertToGUIStyle 

foregroundColor 

visibleRectangle 

IHandle 

asUnsigned 

IHelpHandler 

hyperlinkS elect 
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Class Name 

Member Function 

IlconControl 

convertToGUIStyle 
vi sibleRectangle 

IListBox 

backgroundColor 

calcMinimumSize 

convertToGUIStyle 

enableNotification 

minimumCharacters 

minimumRows 

setltemHeight 

setMinimumCharacters 

setMinimumRows 

IListB oxDrawItemEvent 

isSelectionStateDrawn 

setS elections tateDrawn 

IListB oxDrawItemHandler 

deselectltem 

drawltem 

handleEventsFor 

selectltem 

setltemSize 

IMenu 

add 

addAsNext 

backgroundColor 

convertToGUIStyle 

disabledBackgroundColor 

disabledForegroundColor 

enableNotification 

foregroundColor 

hiliteB ackgroundColor 

hiliteForegroundColor 

isItemEnabled 

resetB ackgroundColor 

resetDisabledBackgroundColor 

resetDisabledBackgroundColor 

resetForegroundColor 

resetHiliteB ackgroundColor 

resetHiliteForegroundColor 

setForegroundColor 

setHiliteB ackgroundColor 

setHiliteForegroundColor 

IMenuBar 

convertToGUIStyle 

IMenuItem 

convertToGUIStyle 

extendedStyle 

isBitmap 

setExtendedStyle 

IMenuN otify Handler 

di spatchHandlerE vent 

IMultiCellCanvas 

convertToGUIStyle 
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Class Name 

Member Function 

IMultiLineEdit 

backgroundColor 

convertToGUIStyle 

cursorLinePosition 

cursorPosition 

disableUpdate 

enableNotification 

enableUpdate 

foregroundColor 

isWriteable 

setCursorLinePosition 

setCursorPosition 

INotebook 

backgroundColor 
convertToGUIStyle 
hiliteB ackgroundColor 
maj orT abB ackgroundColor 
maj orT abForegroundColor 
minorTabB ackgroundColor 
minorTabForegroundColor 
pageB ackgroundColor 
resetMaj orT abB ackgroundColor 
resetMajorTabForegroundColor 
resetMinorTabB ackgroundColor 
resetMinorTabForegroundColor 
resetPageB ackgroundColor 
setMaj orT abForegroundColor 
setMinorTabB ackgroundColor 
setMinorTabForegroundColor 
setPageB ackgroundColor 
setMaj orT abB ackgroundColor 

IOutlineBox 

convertToGUIStyle 

visibleRectangle 

IPaintEvent 

setGraphicContext 

IProgressIndicator 

backgroundColor 

convertToGUIStyle 

IPushButton 

addB order 
convertToGUIStyle 
hasB order 

removeB order 

IRadioButton 

convertToGUIStyle 
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Class Name 

Member Function 

IRectangle 

centerXCenterY 

centerXMaxY 

centerXMinY 

maxX 

maxXCenterY 

maxXMaxY 

maxXMinY 

maxY 

minX 

minXCenterY 

minXMaxY 

minXMinY 

minY 

IResourceLibrary 

try T oLoadB itmap 
tryToLoadlcon 
tryToLoadMessage 
try T oLoadS tring 

ISWP 

isHide 

isMove 

isShow 

isSize 

isZOrder 

setHide 

setMove 
setNoAdjust 
setS how 
setSizeFlag 
setZOrder 

IScrollBar 

convertToGUIStyle 

enableNotification 

foregroundColor 

hiliteForegroundColor 

ISetCanvas 

setGroupPad 

convertToGUIStyle 

groupPad 

ISettingButton 

enableNotification 

ISlider 

convertToGUIStyle 

ISplitCanvas 

convertToGUIStyle 
resetSplitBarEdgeColor 
resetSplitBarMiddleColor 
setSplitBarEdgeColor 
setSplitBarMiddleColor 
splitB arEdgeColor 
splitB arMiddleColor 
visibleRectangle 
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Class Name 

Member Function 

IStaticText 

backgroundColor 

convertToGUIStyle 

fillColor 

foregroundColor 

resetFillColor 

setFillColor 

IString 

includesMBCS 

isMBCS 

isValidMBCS 

IThread 

autoInitGUI 

messageQueue 

variable 

setAutoInitGUI 

setVariable 

setDefaultAutoInitGUI 

ITitle 

activeColor 

acti veTextB ackgroundColor 
acti veT extForegroundColor 
borderColor 

inactiveColor 

inacti veT extB ackgroundColor 
inacti veT extForegroundColor 
enableNotification 
reset Acti veT extB ackgroundColor 
resetActiveTextForegroundColor 
resetlnactiveTextBackgroundColor 
resetlnactiveTextForegroundColor 
set Acti veT extB ackgroundColor 
set Acti veT extForegroundColor 
setlnacti veT extB ackgroundColor 
setlnacti veT extForegroundColor 
set V ie wN umber 

viewNumber 

I ViewPort 

convertToGUIStyle 
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IWindow activeColor 

addObserver 

applyBidiSettings 

backgroundColor 

borderColor 

capturePointer 

characters ize 

convertToGUIStyle 

di sableNotification 

di sabledB ackgroundColor 

disabledForegroundColor 

dispatchRemainingHandlers 

enableNotification 

enum BidiLayout 

enum BidiNumeralType 

enum BidiTextOrientation 

enum BidiTextShape 

enum BidiTextType 

enum EventType control 

extendedStyle 

font 

foregroundColor 

handle WithParent 

handleWithPointerCaptured 

hasPointerCaptured 

hiliteB ackgroundColor 

hiliteForegroundColor 

inactiveColor 

isBidiSupported 

isEnabled 

isEnabledForNotification 

isGroup 

isTabStop 

isWindowValid 

movePointerTo 

nativeRect 

notificationHandler 

notifyObservers 

observerList 

parentSize 

pointerPosition 
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Class Name 


Member Function 


IWindow cont. releasePointer 

removeAllObservers 

removeObserver 

resetActiveColor 

resetB ackgroundColor 

resetBorderColor 

resetColor 

resetDisabledB ackgroundColor 
resetDisabledForegroundColor 
resetFont 

resetForegroundColor 

resetHiliteB ackgroundColor 

resetHiliteForegroundColor 

resetlnactiveColor 

resetShadowColor 

setActiveColor 

setB ackgroundColor 

setBorderColor 

setDisabledB ackgroundColor 

setDisabledForegroundColor 

setExtendedStyle 

setFont 

setForegroundColor 
setHiliteB ackgroundColor 
setHiliteForegroundColor 
setld 

setlnactiveColor 
setNotificationHandler 
setShadowColor 
shadowColor 
windo w W ithO wner 
windo w W ithParent 


Enhanced Member Functions 

The following classes have changed member functions: 


Class Name 

Member Function 

IApplication 

adjustPriority 


setPriority 

IButton 

highlight 


IButton 

ICanvas 

ICanvas 

ICnrDrawHandler 

ICnrDrawHandler 

ICnrMenuHandler 

ICnrMenuHandler 

IColor 

IColor 
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Class Name 

Member Function 

IComboBox 

add 

setltemText 


remove 

IControl 

IControl 

ICurrentThread 

initializePM 

IDDEClientConversation 

acknowledged 

beginHotLink 

conversationEnded 

data 

endHotLink 

executeAcknowledged 

hotLinklnform 

pokeAcknowledged 

pokeData 

requestData 

IDDETopicServer 

acceptConversation 

acknowledged 

beginHotLink 

conversationEnded 

executeCommands 

hotLinkEnded 

pokeData 

requestData 

requestHotLinkData 

IDMHandler 

setltemProvider 

enableDragDropFor 

enableDragFrom 

enableDropOn 

IDMImage 

IDMImage 

style 

IDMSourceHandler 

sourceBegin 

IDMTargetHandler 

targetDrop 

IDMT argetRenderer 

informSourceOfCompletion 

IEntryField 

clear 


copy 


cut 


selectRange 

IEvent 

setResult 

IEventData 

operator char* 
operator unsigned long 

IFileDialog 

IFileDialog 
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Class Name 

Member Function 

IFont 

setCharHeight 

setCharSize 

setCharWidth 

setFontAngle 

setFontShear 

setName 

setPointSize 

useBitmapOnly 

useNonPropOnly 

useVectorOnly 

IFontDialog 

IFileDialog 

IFontDialogHandler 

modelessResults 

IFrameExtension 

separator 

setSize 

width 

IFrameWindow 

addExtension 

borderHeight 

borderWidth 

IFrameWindow 
notifyOwner 
removeExtension 
setB orderHeight 
setB orderS ize 

setBorderWidth 

setExtensionSize 

tryToLoadDialog 

IHelpHandler 

controlSelect 

handleError 

helpUndefined 

keysHelpId 

menuB arCommand 

openLibrary 

showContents 

showCoverPage 

showHistory 

showlndex 

showPage 

showSearchList 

showTutorial 

subitemN otFound 
swapPage 

IHandle 

operator Value 

IHelpNotifyEvent 

controlld 

IlconControl 

IlconControl 
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Class Name 

Member Function 

IListBox 

add 

locateText 

remove 

setHeight 

setltemText 

IMenu 

IMenu 

IMenuItem 

attribute 

index 

isSubmenu 

isText 

setAttribute 

setlndex 

setStyle 

style 

IMultiLineEdit 

clear 

copy 

cut 

selectRange 

setChangedFlag 

IPaintHandler 

IPaintHandler 

IPrivateResource 

handle 

IProgressIndicator 

setHomePosition 

setPrimaryScale 

IResizeHandler 

IResizeHandler 

IResource 

handle 

IResourceld 

IResourceld 

ISelectHandler 

ISelectHandler 

ISettingButton 

select 

ISharedResource 

handle 

IShowListHandler 

IShowListHandler 

ISize 

asSIZEL 

IStaticText 

setAlignment 

ISubmenu 

addBitmap 

addltem 

addSeparator 

addText 

ISWP 

ISWP 

ITextControl 

ITextControl 

IThread 

setAutoInitPM 

setDefaultAutoInitPM 
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Class Name 

Member Function 

IWindow 

windo w W ithHandle 


window Withld 


Additional Library Enhancements 

Existing member functions have been updated to conform to the following User 
Interface Class Library conventions: 

• Many functions are now declared as "const". 

• Many parameters are now passed by "const" references instead of being passed 
by value. 

• Many functions are now declared as "virtual". 

Many of the include statements in the header files have been replaced with forward 
declares. This was done so that applications will only have required files included. 
You might need to add include statements in your application to replace the removed 
includes. 

In place of FID_CLIENT and 0x8008 for the window identifier of a client window, 
you can now use the #define IC_FRAME_CLIENT_ID. 

Window identifiers of the child windows created by an IViewPort have been changed. 


The changes are: 

Child Window 

Old Window id 

New Window id 

Vertical Scroll Bar 

0x8000 

IC_VIEWPORT_VERTSCROLLBAR 

Horizontal Scroll Bar 

0x8001 

IC_VIEWPORT_HORZSCROLLBAR 

View Rectangle 

0x8002 

IC_VIEWPORT_VIEWRECTANGLE 


IWindow::clipToParent and IWindow::synchPaint have been removed from the default 
style of ICanvas. 

INotebook::setStatusText(const char*) now throws an IlnvalidRequest exception when 
invoked and the page does not allow status text. 

IEntryField::selectedRange() and IMulitLineEdit::selectedRange() throws an 
IlnvalidRequest when invoked and there is no text selected. 

A message box will always have a title bar when IMessage:moveable style is 
specified, even if there is no title text. 


1270 


Open Class Library Reference 



New Styles 


The following classes have new styles: 

Class Name 

New Style 

IComboBox 

readOnlyDropDownType 

IContainerControl 

noSharedObjects 

ISetCanvas 

decksBy Group 


Extended Styles Support 

Extended styles are now supported with the ICLUI framework. New functions have 
been added to the IWindow hierarchy. See Appendix C, “Using Extended Style 
Support” on page 1280 for more details. 
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New Color Support 


The User Interface Class Library has added new support for the setting, querying, and 
resetting of colors. In the previous releases of the User Interface Class Library, each 
class that supported the setting and querying of colors contained a ColorArea 
enumeration along with an implementation of the Iwindow::setColor and 
IWindow::color functions. We no longer advise using this enumeration and the two 
corresponding functions and we have removed them from the interface. They still 
exist for backward compatibility; however, they might be removed in a future release. 

The User Interface Class Library defines a new set of functions for easier color 
manipulation. For example, to set the background color of an IListBox control you 
now use the following: 

listBox->setBackgroundColor(IColor::red); 

To query the background color of the same listbox: 

IColor color = 1istBox->backgroundColor(); 

To set the list box back to its default color: 

1istBox->resetBackgroundColor(); 

These new functions for handling colors mean you no longer have to use different 
ColorArea enumerators for each control class. 

Notes: When you use these functions to implement colors, your controls inherit the 
colors that you specify for their owners if their owners are also their parent. 
You can override the inherited color by explicitly setting the color for the 
specific area of a control. 

Some classes use the color area name, such as foregroundColor, on an area of 
the control that is not related to the name. For example, the system container 
control does not support a border. However, it uses the border color for 
specific areas of the control, such as the title separator color. Consult the 
control documentation in your system reference guide for information on what 
areas of a control use a specific color area name. 
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Figure 12 (Page 1 of 7). Enumerators to New Color Member Functions 

Class 

ColorArea enumerators 

New Color Member Functions 

IButton 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


background 

backgroundColor 
setBackgroundColor 
resetB ackgroundColor 


disabledForeground 

disabledForegroundColor 

setDisabledForegroundColor 

resetDisabledForegroundColor 


highlightForeground 

hiliteForegroundColor 

setHiliteForegroundColor 

resetHiliteForegroundColor 


border 

borderColor 

setBorderColor 

resetBorderColor 

ICanvas 

background 

backgroundColor 

setBackgroundColor 

resetBackgroundColor 

IContainerControl 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


background 

backgroundColor 
setBackgroundColor 
resetB ackgroundColor 


border 

borderColor 

setBorderColor 

resetBorderColor 


highlightForeground 

hiliteForegroundColor 

setHiliteForegroundColor 

resetHiliteForegroundColor 


highlightBackground 

hiliteBackgroundColor 

setHiliteBackgroundColor 

resetHiliteBackgroundColor 

IEntryField 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 
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Figure 12 (Page 2 of 7). Enumerators to New Color Member Functions 

Class 

ColorArea enumerators 

New Color Member Functions 


background 

backgroundColor 
setB ackgroundColor 
resetB ackgroundColor 


disabledForeground 

disabledForegroundColor 

setDisabledForegroundColor 

resetDisabledForegroundColor 


highlightForeground 

hiliteForegroundColor 

setFliliteForegroundColor 

resetFliliteForegroundColor 


border 

borderColor 

setBorderColor 

resetBorderColor 

IFrameWindow 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


background 

backgroundColor 
setB ackgroundColor 
resetB ackgroundColor 


disableB ackground 

disabledB ackgroundColor 
setDisabledB ackgroundColor 
resetDisabledBackgroundColor 


frameB order 

borderColor 

setBorderColor 

resetBorderColor 


shadow 

shadowColor 

setShadowColor 

resetShadowColor 


activeBorder 

activeColor 

setActiveColor 

resetActiveColor 


inactiveBorder 

inactiveColor 

setlnactiveColor 

resetlnactiveColor 

IGroupBox 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 
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Figure 12 (Page 3 of 7). Enumerators to New Color Member Functions 

Class 

ColorArea enumerators 

New Color Member Functions 


border 

borderColor 

setBorderColor 

resetBorderColor 

IListBox 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


background 

backgroundColor 

setBackgroundColor 

resetBackgroundColor 


disabledForeground 

disabledForegroundColor 

setDisabledForegroundColor 

resetDisabledForegroundColor 


highlightForeground 

hiliteForegroundColor 

setHiliteForegroundColor 

resetHiliteForegroundColor 


border 

borderColor 

setBorderColor 

resetBorderColor 

IMenu 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


background 

backgroundColor 
setBackgroundColor 
resetB ackgroundColor 


disableForeground 

disabledForegroundColor 

setDisabledForegroundColor 

resetDisabledForegroundColor 


disableB ackground 

disabledB ackgroundColor 
setDisabledB ackgroundColor 
resetDisabledB ackgroundColor 


highlightForeground 

hiliteForegroundColor 

setHiliteForegroundColor 

resetHiliteForegroundColor 


highlightBackground 

hiliteBackgroundColor 

setHiliteBackgroundColor 

resetHiliteBackgroundColor 
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Figure 12 (Page 4 of 7). Enumerators to New Color Member Functions 

Class 

ColorArea enumerators 

New Color Member Functions 


border 

borderColor 

setBorderColor 

resetBorderColor 

IMultiLineEdit 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


background 

backgroundColor 
setB ackgroundColor 
resetB ackgroundColor 


bordercolor 

borderColor 

setBorderColor 

resetBorderColor 

INotebook 

pageB ackground 

pageB ackgroundColor 
setPageB ackgroundColor 
resetPageB ackgroundColor 


maj orT abForeground 

majorTabForegroundColor 

setMajorTabForegroundColor 

resetMajorTabForegroundColor 


maj 01 T abB ackground 

maj orTabB ackgroundColor 

setMajorTabBackgroundColor 

resetMajorTabBackgroundColor 


minorTabForeground 

minorTabForegroundColor 
setMinorT abForegroundColor 
resetMinorTabForegroundColor 


minorTabB ackground 

minorTabB ackgroundColor 
setMinorT abB ackgroundColor 
resetMinorTabBackgroundColor 


notebookWindowBackground 

backgroundColor 
setB ackgroundColor 
resetB ackgroundColor 


notebookOutline 

borderColor 

setBorderColor 

resetBorderColor 


statusLineText 

foregroundColor 

setForegroundColor 

resetForegroundColor 
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Figure 12 (Page 5 of 7). Enumerators to New Color Member Functions 

Class 

ColorArea enumerators 

New Color Member Functions 


selectionCursor 

hiliteBackgroundColor 

setHiliteBackgroundColor 

resetHiliteBackgroundColor 

IOutlineBox 

fillRegion 

foregroundColor 

setForegroundColor 

resetForegroundColor 

IProgressIndicator 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


background 

backgroundColor 
setBackgroundColor 
resetB ackgroundColor 


border 

borderColor 

setBorderColor 

resetBorderColor 

IScrollBar 

shaft 

foregroundColor 

setForegroundColor 

resetForegroundColor 


scrollBox 

hiliteForegroundColor 

setHiliteForegroundColor 

resetHiliteForegroundColor 


border 

borderColor 

setBorderColor 

resetBorderColor 

ISetCanvas 

background 

backgroundColor 

setBackgroundColor 

resetBackgroundColor 

ITextSpinButton 

INumericSpinButton 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


disabledForeground 

disabledForegroundColor 

setDisabledForegroundColor 

resetDisabledForegroundColor 


highlightForeground 

hiliteForegroundColor 

setHiliteForegroundColor 

resetHiliteForegroundColor 
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Figure 12 (Page 6 of 7). Enumerators to New Color Member Functions 

Class 

ColorArea enumerators 

New Color Member Functions 


border 

borderColor 

setBorderColor 

resetBorderColor 

ISplitCanvas 

splitBarEdge 

splitB arEdgeColor 
setSplitBarEdgeColor 
resetSplitB arEdgeColor 


splitBarMiddle 

splitB arMiddleColor 
setSplitBarMiddleColor 
resetSplitB arMiddleColor 

IStaticText 

foreground 

foregroundColor 

setForegroundColor 

resetForegroundColor 


background 

backgroundColor 
setB ackgroundColor 
resetB ackgroundColor 


fill 

fillColor 

setFillColor 

resetFillColor 

ITitle 

activeFill 

activeColor 

setActiveColor 

resetActiveColor 


inactiveFill 

inactiveColor 

setlnactiveColor 

resetlnactiveColor 


activeT extForeground 

activeTextForegroundColor 

setActiveTextForegroundColor 

resetActiveTextForegroundColor 


inactiveTextForeground 

inactiveTextForegroundColor 

setlnactiveTextForegroundColor 

resetlnactiveTextForegroundColor 


acti veTextB ackground 

activeTextBackgroundColor 
setActiveTextBackgroundColor 
resetActiveTextB ackgroundColor 


inactiveTextB ackground 

inactiveTextBackgroundColor 

setlnactiveTextBackgroundColor 

resetlnactiveTextBackgroundColor 
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Figure 12 (Page 7 of 7). Enumerators to New Color Member Functions 

Class 

ColorArea enumerators 

New Color Member Functions 


border 

borderColor 

setBorderColor 

resetBorderColor 

IViewPort 

fillBackground 

backgroundColor 
setBackgroundColor 
resetB ackgroundColor 
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Using Extended Style Support 


The extended style support provides solutions to a number of window style issues 
when using the User Interface Class Library: 

• Overlapping style bit definitions for both OS/2 Presentation Manager 

• User Interface Class Library usage of reserved window style bits in the Os/2 
Version 2.x operating system (that may be used in a future release of the 
platform) 

• Usage of unused window style bits to represent other style bits (for example, 
IStaticText). 

• Extended style support implemented directly within the class (for example, the 
canvas classes) 

• No simple method to extend existing control set and add extended style support, 
such as building a composite custom control. 

• Portability concerns 

The objectives of the new extended style support are as follows: 

• No breakage of the existing styles support 

• Easy integration with the existing styles support 

• Reserved published ranges for the User Interface Class Library, as well as 
customer extended styles bits 

• Assist porting efforts 

The key function convertToGUIStyle( const IBitFlag& style, Boolean extended ) 
allows the individual classes to accept a style object, and resolve the base and 
extended styles that it contains into a window style. You pass this window style to 
the underlying platform during window creation. 

The key parameter, const IBitFlag& style , exposes the IBitFlag class, because you 
cannot truly inherit a style class. For example, ICanvas derived classes use IControl 
styles due to friendship, not inheritance. 

Currently, we reserve the extended style bits as follows: 

Bits 0-23 are reserved for the User Interface Class Library 
Bits 24-31 are open for your usage 
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The User Interface Class Library requires 24-Bits due to the proliferation of styles in 
ISetCanvas and ISetCanvas derived classes such as the tool bar classes. 

Base styles are those window styles that are predefined for each control on the 
supported platform. An example of a base style would be the OS/2 Presentation 
Manager window style, WSJVISIBLE. WSJVISIBLE is exposed in the User 
Interface Class Library as IWindow::visible. 

The following is an example of initializing a base style: 
const IWindow::Sty1e IWindow::visib1e = WS_VISIBLE; 

Extended styles define styles that you do not see predefined for the supported 
platform. The User Interface Class Library has enhanced the extended styles 
definitions to handle the following scenarios: 

• Definition of an extended style where the base style is defined to be 0. An 
example is the OS/2 Presentation Manager button style, BS_PUSHBUTTON. 

The User Interface Class Library defines a unique nonzero bit value that allows 
you to safely use the bitwise operator, &, to test for the existence of this 
extended style rather than using a masking and comparison technique that you 
would normally perform against the base style. 

• Definition of an extended style where the base style bit value overlaps with 
another style. An example is the OS/2 Presentation Manager entryfield style, 
ES_MIXED. The User Interface Class Library defines a unique bit value that 
allows you to safely use the bitwise operator, &, to test for the existance of this 
extended style rather than using a comparison technique that you would normally 
perform against the base style. Note also that the overlapping bits create bitwise 
testing problems for the entryfield styles that they overlap: ES_SBCS and 
ES_DBCS. 

The following is an example of initializing an extended style: 

const ISetCanvas::Style ISetCanvas::packTight ( 0, ICNV_PACKTIGHT ); 

The following sections discuss the classes that we modified to add the extended styles 
support. 


IBitFlag 

The IBitFlag class was modified to accommodate the extended styles support. The 
following function is added: 

asExtendedULong 

Converts the upper 32-Bits of the object to an unsigned long value. 
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For example: 
unsigned long 

asExtendedllnsignedLong ( ) const; 

Additionally, the protected IBitFlag constructor was modified to add a parameter to 
represent the extended style, extendedValue. Note how a default value is being 
assigned to allow existing style implementations to work: 

IBitFlag ( unsigned long value, 

unsigned long extendedValue = 0 ); 

The protected function, setValue, was modified to support extended styles as well. 
Again, note the default value assigned to the parameter, extendedValue , that allow 
existing style implementations to work: 

IBi t FI ag 

&setValue ( unsigned long value , 

unsigned long extendedValue = 0 ); 


IWindow 

To parallel the functions style and setStyle, two new protected functions are added to 
support extended styles: 

extendedStyle 

Returns an unsigned long representing the window’s extended style. 

setExtendedStyle 

Sets the extended window style. 

virtual IWindow 

&setExtendedStyle ( unsigned long extendedStyle ); 
virtual unsigned long 
extendedStyle ( ) const; 

To use extended styles, use the following steps in your constructors to properly save 
the extended styles: 

1. Query the existing existing extended styles using IWindow::extendedStyle. Use 
IMenuItem::extendedStyle for menu items. 

2. Use the bitwise OR operator (I) to include your extended styles with the existing 
extended styles. 

3. Set the new extended styles using IWindow::setExtendedStyle. Use 
IMenuItem::setExtendedStyle for menu items. 
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For example: 

FooClass :: FooClass( unsigned long ulld, 

IWindow* pParent, 

IWindow* pOwner, 

const IRectangle& rectlnit, 
const Style& style ) 

: IControl( ) 

{ 

// Save the extended style to make sure a copy of it stored 
setExtendedStyle( extendedStyle() | style.asExtendedUnsignedLong() ); 

' } 

To support both the base and extended styles, another virtual function was added that 
has the ability to convert the base or extended styles into a style that can be 
understood by the underlying platform: 

convertT oGUIStyle 

Use this function to convert style bits into the style value that can be 
processed by the GUI. The default action is to return the base GUI style 
for the platform. Extended styles which are defined by the User Interface 
Class Library, can be returned by setting the extended parameter to true. 

For example: 

virtual unsigned long 

convertToGUIStyle ( const IBitFlag& style, 

Boolean extended = false ) const; 

The first parameter is a reference to a style object that you pass on various User 
Interface Class Library constructors. Use the second parameter to return the style 
information from the extended portion of the style object. The second parameter can 
simplify processing of the extended style in your classes. An User Interface Class 
Library example is IFrameWindow, as we use it to return information on the frame 
control flags which are passed as an extended style. 

The intent of convertToGUIStyle is to allow you to override it throughout the 
IWindow class hierarchy to allow your classes to parse style information that is 
pertinent to the creation of your window. Note that we implement the 
convertToGUIStyle function in this fashion within the User Interface Class Library, 
and have listed our classes below. 

For example: 
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FooClass :: FooClass( unsigned long ulId, 

IWindow* pParent, 

IWindow* pOwner, 

const IRectangle& rectlnit, 
const Style& style ) 

: IControl( ) 

{ 

// Save the extended style to make sure a copy of it stored 
setExtendedStyle( extendedStyleQ | style.asExtendedUnsignedLong() ); 

// 

IWindowhlandle whFooControl = 
create( ulld, 

0 , 

convertToGUIStyle( style ), 

"FooWindow" 
pParent->handle(), 

(pOwner == 0) ? IWi ndowhlandl e(0) : pOwner->handl e(), 
rectlnit, 

0, 

0 ); 

} 

unsigned long FooClass :: convertToGUIStyle( const IBitFIag& guiStyle, 

Boolean bExtOnly ) const 

{ 

// Obtain the style from the class (IControl) that we inherit from 
unsigned long ulStyle = Inherited::convertToGUIStyle( guiStyle, bExtOnly ); 

if (bExtOnly) 

{ 

// Use mask to only return extended styles in the user defined range 
ulStyle |= extendedStyle() & IS_EXTMASK; 

1 

el se 

{ 

// Mask out F00_ 

ulStyle |= guiStyle.asUnsignedLong() & F00_MASK; 


return( ulStyle ); 

} 
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IMenultem 

The class IMenultem is a special case. We implement the extended styles support in 
IMenultem that is present in IWindow. IMenultem is not derived from IWindow. 
Therefore, the extended styles implementation we describe for IWindow applies to 
IMenultem as well. 


Classes that Implement or Override the convertToGUIStyle Function 


IAnimatedButton 

IBitmapControl 

ICanvas 

ICheckBox 

IComboBox 

IContainerControl 

ICustomButton 

IDrawingCanvas 

IEntryField 

IFileDialog 

IFontDialog 

IFrameWindow 

IGraphicPushButton 

IGroupBox 

IlconControl 

IFistBox 

IMenu 

IMenuBar 

IMenultem 

IMultiCellCanvas 


IMultiFineEdit 

INotebook 

INumericSpinButton 

IOutlineBox 

IProgressIndicator 

IPushButton 

IRadioButton 

IScrollBar 

ISetCanvas 

ISplitCanvas 

IStaticText 

ITextSpinButton 

IToolBar 

IToolBarButton 

IT oolB arContainer 

IViewPort 

IWindow 

I3StateCheckBox 
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Obsolete & Ignored Members Cross-Reference 


This appendix contains the following cross-reference tables: 

“Obsolete Classes and Members” 

Lists obsolete classes and members, and their replacements, if any. 

“Ignored Classes and Members” on page 1289 

Lists classes and members that the User Interface Class Library for AIX does 
not support and subsequently ignores. 


Obsolete Classes and Members 

Lists obsolete classes and members, and their replacements, if any. 

The User Interface Class Library has added new support for the setting, querying, and 
resetting of colors. See Appendix B, “New Color Support” on page 1272 for 
information on obsolete and replacement members for colors. 


Class 

Member 

Replacement 

IAccelerator 

unset 

reset 

IContainerColumn 

isHeadingReadOnly 

isHeadingW riteable 


isReadOnly 

isWriteable 

IContainerControl 

detailObjectRectangle 

detailsObjectRectangle 


(both versions) 



isReadOnly 

isWriteable 

IContainerObject 

iconOffset 

None 


iconTextOffset 

None 


isReadOnly 

isWriteable 

ICurrentThread 

initializePM 

initializeGUI 


isPMInitialized 

isGUIInitialized 


terminatePM 

terminateGUI 

IDMT argetOperation 

setContainerNoRefresh 

IDMOperation::setContainerRefreshOff 


setContainerRefresh 

IDMOperation:: setContainerRefreshOn 

IEntryField 

isReadOnly 

isWriteable 

IFont 

enum Direction bottomTop 

enum Direction bottomToTop 


enum Direction leftRight 

enum Direction leftToRight 


enum Direction rightLeft 

enum Direction rightToLeft 


enum Direction topBottom 

enum Direction topToBottom 
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Class 

Member 

Replacement 

IFrameWindow 

flagsFrom 

convertToGUIStyle 


styleFrom 

convertToGUIStyle 

IHelpHandler 

hypertextSelect 

hyperlinkSelect 

IHelpHypertextEvent 


IHelpHyperlinkEvent 

IHelp Window 

associateWindow 

setAssociatedWindow 


helpForWindow 

None 

IListBox 

setHeight 

setltemHeight 

ILi stB oxDra wltemHandler 

draw 

drawltem 


drewSelected 

setSelectionStateDrawn 


highlight 

selectltem 


setHeight 

setltemSize 


unhighlight 

deselectltem 

IMenu 

addAt 

add 


addNextAt 

addAsNext 


isItemDisabled 

isItemEnabled 


isVerticalFlip 

None 


setVerticalFlip 

None 


verticalFlip 

None 

IMouseClickHandler 


IMouseHandler 

IMultiLineEdit 

cursor 

cursorPosition 


disableRefresh 

disableUpdate 


enableRefresh 

enableUpdate 


isReadOnly 

isWriteable 


removeChangedFlag 

resetChangedFlag 


setCursorAt 

setCursorPosition 


setCursorAtLine 

setCursorLinePosition 

IPushButton 

disableBorder 

removeBorder 


enableBorder 

addB order 


isBorder 

hasB order 

ISpinButton 


IBaseSpinButton 

INumericSpinButton 

ITextSpinButton 

ISubmenu 

addAt 

add 


addNextAt 

addAsNext 

IThread 

autoInitPM 

autoInitGUI 


defaultAutoInitPM 

defauitAutoInitGUI 


setAutoInitPM 

setAutoInitGUI 


setDefaultAutoInitPM 

setDefaultAutoInitGUI 
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Class 

Member 

Replacement 

ITitle 

setViewNum 

setViewNumber 


viewNum 

viewNumber 

IWindow 

handleWithld 

handleWithParent 


isDisabled 

isEnabled 


windowWithld 

windowWithOwner 
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Ignored Classes and Members 

Lists classes and members that the User Interface Class Library for AIX does not 

support and subsequently ignores. 

A single asterisk (*) means this member is overloaded and you must look it up to 

determine which overload the AIX release ignores. 

A double asterisk (**) means this class is not ported to the AIX platform. 

Figure 13 (Page 1 of 14). Ignored members in Motif 

Class Member 

I3StateCheckBox ** 

I3StateCheckBox::Style ** 

IAccelerator handle 

isSet 
remove 
reset 
set * 


IAccelTblHandle 
I AnchorB lockHandle 

IBaseSpinButton alignment 

setAlignment 

IButton allowsMouseClickFocus 

disableMouseClickFocus 

enableMouseClickFocus 

highlight 

isHighlighted 

unhighlight 

ICnrBeginEditEvent ** 

ICnrDrawBackgroundEvent ** 

ICnrDrawHandler ** 

ICnrDrawItemEvent ** 

ICnrEditEvent ** 

ICnrEditHandler ** 

ICnrEndEditEvent ** 

ICnrEnterEvent 
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Figure 13 (Page 2 of 14). Ignored members in Motif 


Class 

Member 

ICnrHandler 

cursoredChanged 

deltaReached 

inuseChanged 

windowScrolled 

ICnrMenuHandler 

addSourceEmphasis 

removeSourceEmphasis 

ICnrQueryDeltaEvent ** 

atBottomDelta 

atFirstObject 

atLastObject 

atTopDelta 

ICnrQueryDeltaEvent 

'ICnrQueryDeltaEvent 

ICnrReallocStringEvent ** 

ICnrScrollEvent 

amount 

ICnrScrollEvent 

isHorizontal 

isLeftDetails 
isRightDetails 
is Vertical 

'ICnrScrollEvent 
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Figure 13 (Page 3 of 14). Ignored members in Motif 


IContainerColumn 


Member 

data Attributes 

disableDataUpdate 

disableHeadingUpdate 

displayWidth 

enableDataUpdate 

enableHeadingUpdate 

headinglcon 

hideSeparators 

horizontalDataAlignment 

horizontalHeadingAlignment 

isHeadinglconHandle 

isHeadingReadOnly 

isHeadingString 

isHeadingWriteable 

isReadOnly 

isWriteable 

justifyData 

justifyHeading 

setDataAttributes 

setDisplay Width 

setHeadinglcon * 

setTitleAttributes 

showSeparators 

title Attributes 

verticalDataAlignment 

verticalHeadingAlignment 
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Figure 13 (Page 4 of 14). Ignored members in Motif 

Class 

IContainerControl 
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Member 

areDetailsViewTitlesVisible 

closeEdit 

collapse 

collapseTree 

columnUnderPoint 

convertT oW orkspace 

currentEditColumn 

currentEditMLE 

currentEditObject 

cursoredObject 

detailObjectRectangle * 

detailsObjectRectangle * 

detailsTitleRectangle 

details V ie wPortOnW indo w 

details V ie wPortOnW orkspace 

detailsViewSplit 

disableCaching 

disableDataUpdate 

disableDrawBackground 

disableDrawItem 

disableDrop 

disableTitleUpdate 

editColumnTitle 

editContainerTitle 

editObject 

enableCaching 

enableDataUpdate 

enableDrawB ackground 

enableDrawItem 

enableDrop 

enableTitleUpdate 

expand 

expandTree 

hasMixedTargetEmphasis 

hasN ormalT argetEmphasis 

hasOrderedTargetEmphasis 

hideSourceEmphasis * 

hideSplitBar 

hideTitle 

hideTitleSeparator 
iconRec tangle 
iconSize 



Figure 13 (Page 5 of 14). Ignored members in Motif 

Class Member 

isCachingEnabled 
isCollapsed 
isColumnRight 
isCursored 

isDrawB ackgroundEnabled 
isDrawItemEnabled 
isDropOnAble 
isExpanded 
isInUse 
isReadOnly 
isRefreshOn 
isSource 
isTarget 

isTitleSeparatorVisible 
isTitleVisible 
isTitleWriteable 
isVisible * 
isWriteable 
lineSpacing 
movelconTo 
objectAt * 
objectUnderPoint 
refresh * 

refreshAllContainers 
removelnUse 
scroll 

scrollDetailsHorizontally 
scrollHorizontally 
scrollToObject * 
scroll Vertically 
setCursor 

setDetailsViewSplit 
setEditColumn 
setEditMLE 
setEditObject 
setlconSize 
setlnUse 
setLineSpacing 
setMixedT argetEmphasis 
setNormalTargetEmphasis 
setOrderedT argetEmphasis 
setRefreshOff 
setRefreshOn 


IContainerControl cont. 
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Figure 13 (Page 6 of 14). Ignored members in Motif 


Class 

Member 

IContainerControl cont. 

setTitle * 

setTitleAlignment 

setTreeExpandlconSize 

showSourceEmphasis * 

showSplitBar 

showTitle 

showTitleSeparator 

splitBarOffset 

textRectangle 

title 

titleRectangle 
viewPortOnWindow 
vie wPortOnW orkspace 

IContainerObject 

disableDataUpdate 

disableDrop 

enableDataUpdate 

enableDrop 

handleCursoredChange 

handlelnuseChange 

iconOffset 

iconTextOffset 

isDropOnAble 

isInUse 

isReadOnly 

isRefreshOn 

isWriteable 

refresh 

removelnUse 

setlnUse 

setRefreshOff 

setRefreshOn 

IControl 

disableGroup 

disableTabStop 

enableGroup 

enableTabStop 

isGroup 

isTabStop 

ICurrentThread 

remainingStack 

suspend 

waitFor 

waitForAOThreads 
waitForAny Thread 
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Figure 13 (Page 7 of 14). Ignored members in Motif 

Class Member 

IDDEAcknowledgeEvent ** 
IDDEAcknowledgeExecuteEvent ** 
IDDEAcknowledgePokeEvent ** 

IDDEActiveServer ** 

IDDEActiveServerSet ** 

IDDEBeginEvent ** 

IDDEClientAcknowledgeEvent ** 

IDDEClientConversation ** 

IDDEClientEndEvent ** 

IDDEClientHotLinkEvent ** 

IDDEClientHotLinkSet ** 

IDDEDataEvent ** 

IDDEEndEvent ** 

IDDEEvent ** 

IDDEExecuteEvent ** 

IDDEPokeEvent ** 

IDDERequestDataEvent ** 

IDDEServerAcknowledgeEvent ** 
IDDEServerHotLinkEvent ** 
IDDESetAcknowledgelnfoEvent ** 

IDDETopicServer ** 

IDeviceColor 
IDMCnrltem ** 

IDMEFItem ** 


IDMEvent ** 
IDMHandler ** 
IDMImage ** 
IDMItem ** 
IDMItemProvider ** 
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Figure 13 (Page 8 of 14). Ignored members in Motif 

Class Member 

IDMItemProviderFor ** 

IDMMLEItem ** 

IDMOperation ** 

IDMRenderer ** 

IDMSourceBeginEvent ** 

IDMSourceDiscardEvent ** 

IDMSourceEndEvent ** 

IDMSoureeHandler ** 

IDMSourceOperation ** 

IDMSourcePrepareEvent ** 

IDMSourcePrintEvent ** 

IDMSourceRenderer ** 

IDMSourceRenderEvent ** 

IDMTargetDropEvent ** 

IDMTargetEndEvent ** 

IDMTargetEnterEvent ** 

IDMTargetHandler ** 

IDMTargetHelpEvent ** 

IDMTargetLeaveEvent ** 

IDMTargetOperation ** 

IDMTargetRenderer ** 

IDrawItemEvent ** 

IDynamicLinkLibrary 

IEntryField setAlignment 

setCharType 

IEnumHandle 

IFileDialog::Settings addDrive 

addFileType 
setlnitialDrive 
setlnitialFileT ype 
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Figure 13 (Page 9 of 14). Ignored members in Motif 

Class 

Member 

IFont 

isOutline 

isStrikeout 

isUnderscore 

setCharHeight 

setCharSize 

setCharWidth 

setDirection 
setFont Angle 
setFontShear 

setOutline 

setStrikeout 

setUnderscore 

IFont: :FaceNameCursor 

IFont: :PointSizeCursor 

IFontDialog 

fontWeight 

fontWidth 

IFontDialog::Settings 

setDisplayPS 

setPrinterPS 

IFrameFormatEvent 

clientRect 

IFrameFormatEvent 

setClientRect 
swp Array 

'IFrameFormatEvent 

IFrameHandler 

deactivated 

draw 

format 

positionExtensions 


© IBM Corp. 1992, 1995 


Appendix D. Obsolete & Ignored Members Cross-Reference 1297 



Figure 13 (Page 10 of 14). Ignored members 

in Motif 

Class 

Member 

IFrameWindow 

addToWindowList 
beginFlashing 
borderFleight 
borders ize 

borderWidth 

endFlashing 

isFlashing 

isMaximized 

maximize 

maximizeRect 

minimizeRect 

nextShellRect 

removeFromWindowList 

restore 

restoreRect 
setBorderFleight 
setBorderSize * 

setBorderWidth 

setRestoreRect 

shareParentDBCSStatus 

usesDialogBackground 

IGraphicPushButton 

disableSizeToGraphic 
enable SizeT oGraphic 
marginSize 
setMarginSize 

IGroupB ox 

calcMinimumSize 

defaultStyle 

foregroundColor 

moveSizeTo 

position 

rect 

setDefaultStyle 
setText * 

size 


IGroupB ox:: S ty le 
IGUIColor 
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Figure 13 (Page 11 of 14). Ignored members 

in Motif 

Class 

Member 

IHelpHandler 

openLibrary 

showContents 

showCoverPage 

showHistory 

showlndex 

showPage 

showSearchList 

swapPage 

IlnfoArea 

setResourceLibrary * 

IListBox 

disableNoAdjustPosition 

enableNoAdjustPosition 

isNoAdjustPosition 

IListBoxDrawItemEvent ** 

IListBoxDrawItemHandler ** 

IListBoxDrawItemHandler: :DrawFlag ** 

IMenu 

removeConditionalCascade 

setConditionalCascade 

IMenuDrawItemEvent ** 

IMenuDrawItemHandler ** 

IMenuDrawItemHandler: :DrawFlag * * 

IMenuItem 

isDrawItem 

isFramed 

isHighlighted 

isNoDismiss 

setDrawItem 

setFramed 

setHighlighted 

setNoDismiss 

IMessageQueueHandle 

IModuleHandle 

IMultiCellCanvas 

disableDragFines 

disableGridFines 

enableDragLines 

enableGridFines 

hasDragLines 

hasGridLines 
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Figure 13 (Page 12 of 14). Ignored members 

in Motif 

Class 

Member 

IMultiLineEdit 

isUndoable 

setTab 

undo 

INotebook 

hiliteB ackgroundColor 

resetBackgroundMajorColor 

resetBackgroundMinorColor 

resetBackgroundPageColor 

resetForegroundMajorColor 

resetForegroundMinorColor 

setMajorTabSize 

setMinorTabSize 

setPageButtonSize 

setTabShape 

tabShape 

INotebookDrawItemEvent ** 

INotifier 

IPageHandler 

help 


remove 


resize 

IPageHelpEvent 

helpWindow 

IPageHelpEvent * 
notebook 
pageHandle 
'IPageHelpEvent 

IPageRemoveEvent 

IPageRemoveEvent * 

notebook 

pageWindow 

tabBitmap 

'IPageRemoveEvent 

IProcedureAddress 

IProfile 

numberOfApplications 

IProgressIndicator 

disableDrawItem 

enableDrawItem 

isDrawItemEnabled 

setShaftPosition 
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Figure 13 (Page 13 of 14). Ignored members 

in Motif 

Class 

Member 

IRadioButton 

disable AutoSelect 
disableCursorSelect 
enable AutoSelect 

enableCursorSelect 

isAutoSelect 

isCursorSelect 

IRegionHandle 

ISlider 

addDetent 

detentPosition 

removeDetent 

setArmSize 

ISliderDrawHandler ** 

ISpinButton 

alignment 

setAlignment 

ISplitCanvas 

resetSplitBarEdgeColor 

resetSplitBarMiddleColor 

setSplitBarEdgeColor 

splitBarEdgeColor 

ISWP 

ISWP Array 

ISystemBitmapHandle ** 

ISystemMenu 

ISystemMenu * 

IThread 

adjustPriority 
defaultQueueSize 
defaults tackSize 
priori tyClass 
priority Level 
queueSize 


resume 


setDefaultQueueSize 

setDefaultStackSize 

setPriority 

setQueueSize 

setStackSize 

stacks ize 

suspend 
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Figure 13 (Page 14 of 14). Ignored members 

in Motif 

Class 

Member 

ITitle 

activeColor 

activeTextBackgroundColor 
activeT extForegroundColor 
borderColor 

inactiveColor 

inactiveTextBackgroundColor 

inactiveTextF oregroundColor 

resetActiveTextBackgroundColor 

resetActiveTextForegroundColor 

resetlnactiveTextBackgroundColor 

resetlnactiveTextForegroundColor 

setActiveTextBackgroundColor 

setActiveT extForegroundColor 

setlnactiveTextBackgroundColor 

setlnactiveTextForegroundColor 

IWindow 

activeColor 

disabledBackgroundColor 

disabledForegroundColor 

dispatch 

hiliteB ackgroundColor 

hiliteForegroundColor 

inactiveColor 

resetActiveColor 

resetBackgroundColor 

resetBorderColor 

resetDisabledB ackgroundColor 

resetDisabledForegroundColor 

resetForegroundColor 

resetFliliteB ackgroundColor 

resetFliliteForegroundColor 

resetlnactiveColor 

resetShadowColor 

setActiveColor 

setDisabledBackgroundColor 

setDisabledForegroundColor 

setFliliteB ackgroundColor 

setHiliteForegroundColor 

setld 

setlnactiveColor 

setParent 

setShadowColor 

setStyle 

shadowColor 

style 
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Handlers for Controls Cross-Reference 


The following table lists the handlers that you can attach to User Interface Class 
Library control class objects. 


Handler 

Control 

IClipBoardHandler 

IFrameWindow 

ICnrDrawHandler 

IContainerControl 

ICnrEditHandler 

IContainerControl 

ICnrHandler 

IContainerControl 

ICnrMenuHandler 

IContainerControl 

IC ommandHandler 

IPushButton and owner 

IGraphicsPushButton 

IMenu and owner 

IFrameWindow 

IDMSourceHandler 

Any window if you provide the support. 

IDMT arge tHandler 

Any window if you provide the support. 

IEditHandler 

ICircularSlider and owner 

IComboBox and owner 

IEntryField and owner 

IMultiLineEdit and owner 

INumericSpinButton and owner 

IProgressIndicator and owner 

ISlider and owner 

ITextSpinButton and owner 

IFileDialogHandler 

IFileDialog 

IFlyOverHelpHandler 

IFrameWindow 

IFocusHandler 

ICircularSlider and owner 

IContainerControl and owner 

IEntryField and owner 

IListBox and owner 

IMultiLineEdit and owner 

INumericSpinButton and owner 

IProgressIndicator and owner 

ISlider and owner 

ITextSpinButton and owner 

IFontDialogHandler 

IFontDialog 
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Handler 

Control 

IFrameHandler 

IFrameWindow 

IHelpHandler 

IFrameWindow 

IKeyboardHandler 

ICheckBox 

ICircularSlider 

IComboBox (AIX only) 

IContainerControl 

IEntryField 

IFrameWindow 

IListBox 

IMultiLineEdit 

INotebook 

INumericSpinButton 

IProgessIndicator 

IRadioButton 

ISlider 

ITextSpinButton 

IListBoxDrawItemHandler 

IListBox and owner 

IMenuDrawItemHandler 

IMenuItem 

IMenuHandler 

IFrameWindow 

IMenu 

Any control that owns a menu or 
that contains a pop-up menu 

IMouseHandler 

All visible controls 

IMousePointerHandler 

Any control that can issue 
a WM_CONTROLPOINTER message 

IMMDeviceHandler 

IMMPlayerPanelHandler 

IMMPlayerPanel 

IPageHandler 

INotebook and window owner 

IPaintHandler 

All visible controls 

IResizeHandler 

All visible controls 

IScrollHandler 

IScrollBar (attached only to its owner) 

ISelectHandler 

ICheckBox and window owner 

IComboBox and window owner 

IContainerControl and window owner 

IListBox and window owner 

IRadioButton and window owner 

I3StateCheckBox and window owner 

IShowListHandler 

IComboBox and window owner 
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Handler 

Control 

ISliderDrawHandler 

IProgressIndicator and window owner 

ISlider and window owner 

ISliderArmHandler 

ICircularSlider 

ISlider 

ISpinHandler 

ITextSpinButton and window owner 

INumericSpinButton and window owner 
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Classes and Their Styles Cross-Reference 


The following table shows the styles available for use by a specific class, and whether 
the User Interface Class Library for AIX release supports the style. 


Class 

Styles 

AIX 

I3StateCheckBox::Style 

autoSelect 

No 


classDefaultStyle 

No 

IAnimatedButton:: Style 

animate WhenLatched 

No 


classDefaultStyle 

No 

IBaseComboBox::Style 

anyData 

classDefaultStyle 

No 


dbcsData 
dropDownType 
horizontals croll 

No 


mixedData 

No 


readOnlyDropDownType 

No 


sbcsData 

simpleType 

No 

IBaseListBox::Style 

classDefaultStyle 



drawltem 

extendedSelect 
horizontals croll 
multipleSelect 

No 


noAdjustPosition 

No 

IBaseSpinButton::Style 

centerAlign 

fastSpin 

No 


leftAlign 

master 

noBorder 

readonly 

No 


rightAlign 

servant 

No 

IBitmapControl:: Style 

classDefaultStyle 

sizeToBitmap 


IButton::Style 

noPointerFocus 

No 

ICanvas::Style 

classDefaultStyle 
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Class 

Styles 

AIX 

ICircularSlider:: Style 

buttons 

circular Arm 
clas sDefault Style 
display Value 
full360 

jumpToPointer 

label 

midpoint 

noTicks 

proportionalTicks 


ICanvas::Style 

clas sDefault Style 


IC omboB ox:: S ty le 

clas sDefault Style 


IContainerControl::Style 

autoPosition 

clas sDefault Style 

extendedSelection 

multipleSelection 

noSharedObjects 

readonly 

singleSelection 

verifyPointers 


IControl::Style 

group 

No 


tabStop 

No 

ICustomButton:: Style 

autoLatch classDefaultStyle latchable 


IDrawingCanvas: :Style 

classDefaultStyle useDefaultPaintHandler 


IEntryField::Style 

anyData 

autoScroll 

autoTab 



centerAlign 
clas sDefault Style 

No 


command 

No 


dbcsData 

leftAlign 

margin 

No 


mixedData 

readonly 

No 


rightAlign 

sbcsData 

No 


unreadable 

No 
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Class 

Styles 

AIX 

IFileDialog::Style 

apply Button 
classDefaultStyle 



filter 

helpButton 

No 


includeEAS 

modeless 

multiSelection 

noStyle 

No 


preload 

selectableListbox 

No 

IFontDialog:: S ty le 

apply Button 

bitmapOnly 

classDefaultStyle 

fixedWidthOnly 

helpButton 

modeless 

noStyle 



noSynthesize 

proportionalOnly 

resetButton 

vectorOnly 

No 
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Class 

Styles 

AIX 

IFrameWindow: :Style 

accelerator 



alignNoAdjust 

No 


animated 

No 


appDBCSStatus 

border 

clas sDefault S ty le 
deferCreation 

No 


dialogB ackground 
dialogB order 

No 


hideButton 

horizontalScroll 

maximizeButton 

maximized 

menuBar 

minimizeButton 

No 


minimized 

No 


minimizedlcon 

No 


noMoveWithOwner 

No 


shellPosition 

sizingBorder 

systemMenu 

systemModal 

titleBar 

verticalScroll 

No 


windowList 

No 

IGraphicPushButton: :Style 

clas sDefault S tyle 
sizeToGraphic 


IGroupB ox:: Style 

clas sDefault Style 


IlconControl:: Style 

clas sDefault S tyle 
sizeToIcon 


IListBox:: Style 

clas sDefault S tyle 


IMenu::Style 

clas sDefault S tyle 
noStyle 


IMenuBar::Style 

clas sDefault Style 

empty 

wrapper 
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Class 

Styles 

AIX 

IMenuItem::Style 

buttonSeparator 

classDefaultStyle 

No 


drawltem 

noStyle 

postHelp 

postSystemCommand 

separator 

split 

No 


splitWithSeparator 

unavailable 

No 

IMessageBox::Style 

abortRetry IgnoreB utton 

applicationModal 

cancelButton 

defButtonl 

defButton2 

defButton3 

enterButton 

enterCancelButton 

errorlcon 

informationlcon 

moveable 

noicon 

okB utton 

okCancelButton 

querylcon 

retryCancelButton 

systemModal 

warninglcon 

yesNoButton 

yesNoCancelButton 


IMultiCellCanvas:: Style 

classDefaultStyle 



dragLines 

No 


gridLines 

No 

IMultiLineEdit: :Style 

border 

classDefaultStyle 

horizontals croll 

ignoreTab 

readonly 

verticalScroll 

wordwrap 
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INotebook: :Style backPagesBottomLeft 

backPagesBottomRight 

backPagesTopLeft 

backPagesTopRight 

clas sDefault Style 

majorTabsBottom 

majorTabsLeft 

majorTabsRight 

majorTabsTop 

polygonTabs 

roundedTabs 

solidBinding 

spiralBinding 

squareTabs 

statusTextCenter 

statusTextLeft 

statusTextRight 

tabTextCenter 

tabTextLeft 

tabTextRight 

INumericSpinButton::Style classDefaultStyle 

padWithZeros 

IOutlineBox:: Style backgroundFrame 

clas sDefault Style 
foregroundFrame 

halftoneFrame No 


IProgressIndicator::Style alignBottom 

alignCentered 

alignLeft 

alignRight 

alignTop 

clas sDefault Style 

handleDrawItem No 

homeBottom 

homeLeft 

homeRight 

homeTop 

horizontal 

primary Scale 1 

primaryScale2 

ribbonStrip 

snapToTickMark 

vertical 
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Class 

Styles 

AIX 

IPushButton:: Style 

classDefaultStyle 

defaultButton 

help 

noB order 
systemCommand 


IRadioB utton:: S ty le 

autoSelect 

classDefaultStyle 

No 


noCursorSelect 

No 

IScrollBar::Style 

autoSize 

classDefaultStyle 

horizontal 

vertical 


ISetCanvas:: Style 

bottomAlign 

centerAlign 

centerVerticalAlign 

classDefaultStyle 

decksBy Group 

horizontalDecks 

leftAlign 

packEven 

packExpanded 

packTight 

rightAlign 

topAlign 

verticalDecks 


ISlider::Style 

buttonsBottom 

buttonsLeft 

buttonsRight 

buttonsTop 

classDefaultStyle 


ISplitCanvas:: Style 

classDefaultStyle 

horizontal 

noSplitBars 

vertical 
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Class 

Styles 

AIX 

IStaticText:: Style 

bottom 

center 

clas sDefault Style 
fillBackground 



halftone 

left 

No 


mnemonic 

right 

No 


strikeout 

top 

No 


underscore 

vertCenter 

No 


wordBreak 

No 

ITextSpinButton: :Style 

clas sDefault S tyle 


IToolBar::Style 

buttonB itmapAndText Visible 

buttonB itmap Visible 

buttonText Visible 

clas sDefault S tyle 

filterMisfits 

noDragDrop 


IToolB arB utton:: S ty le 

buttonB itmap AndText Visible 
buttonB itmap Visible 
clas sDefault S tyle 
noDragDrop 
standardFormat 

textVisible 

useldForBitmap 

useldForText 


IToolBarContainer: :Style 

clas sDefault Style 


IViewPort::Style 

alwaysHorizontalScrollBar 

alway s V erticalScrollB ar 

asNeededHorizontalScrollBar 

asNeededVerticalScrollBar 

clas sDefault Style 

noHorizontalScrollBar 

noVerticalScrollBar 

noViewWindowFill 
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Class 

Styles 

AIX 

IWindow::Style 

clipChildren 

No 


clipSiblings 

No 


clipToParent 

disabled 

noStyle 

saveBits 

synchPaint 

visible 

No 
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Classes and Header Files Cross-Reference 


This appendix contains the following cross-reference tables: 

“Classes to Header Files” 

List of classes, showing the header file where each class can be found. 

“Header Files to Classes” on page 1333 

List of header files, showing the classes that each header file contains. 


Classes to Header Files 

The following table shows the header file where a specific class can be found. 


Class Name 

Header File 

Bag 

ibag.h 

Collection 

iacllct.h 

Constant Iterator 

iiter.h 

Cursor 

icursor.h 

Deque 

ideque.h 

Equality Collection 

iaequal.h 

Equality Key Collection 

iaeqkey.h 

Equality Key Sorted Collection 

iaeqksrt.h 

Equality Sequence 

ieqseq.h 

Equality Sorted Collection 

iaeqsrt.h 

Heap 

iheap.h 

IOString 

iOstring.hpp 

I3StateCheckBox 

i3statbx.hpp 

13 S tateCheckBox:: Style 

i3statbx.hpp 

IAccelTblHandle 

ihandle.hpp 

IAccelerator 

iaccel.hpp 

IAccessError 

iexcbase.hpp 

IAnchorBlockHandle 

ihandle.hpp 

IAnimatedButton 

ianimbut.hpp 
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Class Name 

Header File 

IAnimatedButton:: Style 

ianimbut.hpp 

IApplication 

iapp.hpp 

IAssertionFailure 

iexcbase.hpp 

IAutoElemPointer 

iptr.h 

IAutoPointer 

iptr.h 

IBase 

ibase.hpp 

IBase::Version 

ibase.hpp 

IBaseComboBox 

icombobs.hpp 

IBaseComboBox::Cursor 

icombobs.hpp 

IBaseComboBox::Style 

icombobs.hpp 

IBaseListBox 

ilistbas.hpp 

IBaseListBox:: Cursor 

ilistbas.hpp 

IBaseListBox::Style 

ilistbas.hpp 

IBaseSpinButton 

ispinbas.hpp 

IBaseSpinButton::Style 

ispinbas.hpp 

IBitFlag 

ibitflag.hpp 

IBitmapControl 

ibmpctl.hpp 

IBitmapControl:: Style 

ibmpctl.hpp 

IBitmapFlandle 

ihandle.hpp 

IBuffer 

ibuffer.hpp 

IButton 

ibutton.hpp 

IButton::Style 

ibutton.hpp 

IButtonNotifyFlandler 

ibtnnhdr.hpp 

ICLibErrorlnfo 

iexcept.hpp 

ICanvas 

icanvas.hpp 

ICanvas::Style 

icanvas.hpp 

ICheckBox 

icheckbx.hpp 

ICheckBox::Style 

icheckbx.hpp 

ICircularSlider 

icslider.hpp 

ICircularSlider: :Style 

icslider.hpp 
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Class Name 

Header File 

ICircularSliderNotifyHandler 

icsliden.hpp 

IClipboard 

iclipbrd.hpp 

IClipboard: :Cursor 

iclipbrd.hpp 

IClipboardHandler 

icliphdr.hpp 

ICnrAllocator 

icnrobj.hpp 

ICnrBeginEditEvent 

icnreevt.hpp 

ICnrControlList 

icnrclst.hpp 

IC nrDrawB ackgroundE vent 

icnrdiev.hpp 

ICnrDrawHandler 

icnrdihd.hpp 

ICnrDrawItemEvent 

icnrdiev.hpp 

ICnrEditEvent 

icnreevt.hpp 

ICnrEditHandler 

icnrehdr.hpp 

ICnrEmphasisEvent 

icnrevt.hpp 

ICnrEndEditEvent 

icnreevt.hpp 

ICnrEnterEvent 

icnrevt.hpp 

ICnrEvent 

icnrevt.hpp 

ICnrHandler 

icnrhdr.hpp 

ICnrHelpEvent 

icnrevt.hpp 

ICnrMenuHandler 

icnrmhdr.hpp 

ICnrObjectSet 

icnrolst.hpp 

ICnrQueryDeltaEvent 

icnrevt.hpp 

ICnrReallocStringEvent 

icnreevt.hpp 

ICnrScrollEvent 

icnrevt.hpp 

ICollectionViewComboBox 

icombovw.hpp 

ICollectionViewConstants 

icollvwi.hpp 

ICollectionViewListBox 

ilistcvw.hpp 

IColor 

icolor.hpp 

IComboBox 

icombobx.hpp 

IC omboB ox:: S ty le 

icombobx.hpp 

IC omboB oxNotify Handler 

icombonh.hpp 
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Class Name 

Header File 

ICommandEvent 

icmdevt.hpp 

ICommandHandler 

icmdhdr.hpp 

IContainerColumn 

icnrcol.hpp 

IContainerControl 

icnrctl.hpp 

IContainerControl:: Attribute 

icnrctl.hpp 

IContainerControl: :ColumnCursor 

icnrctl.hpp 

IContainerControl: :CompareFn 

icnrctl.hpp 

IContainerControl: :FilterFn 

icnrctl.hpp 

IContainerControl: iterator 

icnrctl.hpp 

IContainerControl: :ObjectCursor 

icnrctl.hpp 

IContainerControl: :Style 

icnrctl.hpp 

IContainerControl: :TextCursor 

icnrctl.hpp 

IContainerControlNotifyHandler 

icnrnhdr.hpp 

IContainerObject 

icnrobj.hpp 

IContextFIandle 

ihandle.hpp 

IControl 

icontrol.hpp 

IControl::Style 

icontrol.hpp 

IControlEvent 

ictlevt.hpp 

ICoordinateSystem 

icoordsy.hpp 

ICritSec 

icritsec.hpp 

ICurrentApplication 

iapp.hpp 

ICurrentThread 

ithread.hpp 

ICustomButton 

icustbut.hpp 

ICustomButton: :Style 

icustbut.hpp 

ICustomButtonDrawEvent 

icustbev.hpp 

ICustomButtonDrawFIandler 

icustbhd.hpp 

IDBCSBuffer 

idbcsbuf.hpp 

IDDE 

iddecomm.hpp 

IDDEAcknowledgeEvent 

iddeevt.hpp 

IDDEAcknowledgeExecuteEvent 

iddeevt.hpp 
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Class Name 

Header File 

IDDEAcknowledgePokeEvent 

iddeevt.hpp 

IDDEActiveServer 

iddecset.hpp 

IDDEActiveServerSet 

iddecset.hpp 

IDDEBeginEvent 

iddeevt.hpp 

IDDEClientAcknowledgeEvent 

iddeevt.hpp 

IDDEClientConversation 

iddeccnv.hpp 

IDDEClientEndEvent 

iddeevt.hpp 

IDDEClientHotLinkEvent 

iddeevt.hpp 

IDDEClientHotLinkSet 

iddecset.hpp 

IDDEDataEvent 

iddeevt.hpp 

IDDEEndEvent 

iddeevt.hpp 

IDDEEvent 

iddeevt.hpp 

IDDEExecuteEvent 

iddeevt.hpp 

IDDEPokeEvent 

iddeevt.hpp 

IDDERequestDataEvent 

iddeevt.hpp 

IDDEServerAcknowledgeEvent 

iddeevt.hpp 

IDDEServerHotLinkEvent 

iddeevt.hpp 

IDDESetAcknowledgelnfoEvent 

iddeevt.hpp 

IDDETopic S erver 

iddetsrv.hpp 

IDM 

idmcomm.hpp 

IDMCnrltem 

idmcnrit.hpp 

IDMEFItem 

idmefit.hpp 

IDMEvent 

idmevent.hpp 

IDMHandler 

idmhndlr.hpp 

IDMImage 

idmimage.hpp 

IDMImage:: Style 

idmimage.hpp 

IDMItem 

idmitem.hpp 

IDMItemProvider 

idmprov.hpp 

IDMItemProviderFor 

idmprov.hpp 

IDMMLEItem 

idmmleit.hpp 
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Class Name 

Header File 

IDMMenuItem 

idmmenit.hpp 

IDMOperation 

idmoper.hpp 

IDMRenderer 

idmrendr.hpp 

IDMSourceBcginEvent 

idmevent.hpp 

IDMSourceDiscardEvent 

idmevent.hpp 

IDMSourceEndEvent 

idmevent.hpp 

IDMSourceHandler 

idmsrch.hpp 

IDMSourceOperation 

idmsrcop.hpp 

IDMSourcePrepareEvent 

idmevent.hpp 

IDMSourcePrintEvent 

idmevent.hpp 

IDMSourceRenderEvent 

idmevent.hpp 

IDMSourceRenderer 

idmsrcrn.hpp 

IDMTB arB uttonltem 

idmtbbit.hpp 

IDMT argetDropE vent 

idmevent.hpp 

IDMTargetEndEvent 

idmevent.hpp 

IDMTargetEnterEvent 

idmevent.hpp 

IDMT argetE vent 

idmevent.hpp 

IDMTargetHandler 

idmtgth.hpp 

IDMTargetHelpEvent 

idmevent.hpp 

IDMTargetLeaveEvent 

idmevent.hpp 

IDMT argetOperation 

idmtgtop.hpp 

IDMT argetRenderer 

idmtgtrn.hpp 

IDMToolBarltem 

idmtbrit.hpp 

IDate 

idate.hpp 

IDeviceColor 

icolor.hpp 

IDeviceError 

iexcbase.hpp 

IDisplayHandle 

ihandle.hpp 

IDrawItemEvent 

idievt.hpp 

IDrawingCanvas 

idrawcv.hpp 

IDrawingCanvas: :Style 

idrawcv.hpp 
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Class Name 

Header File 

IDynamicLinkLibrary 

ireslib.hpp 

IEditHandler 

iedithdr.hpp 

IElemPointer 

iptr.h 

IEntryField 

ientryfd.hpp 

IEntryField::Style 

ientryfd.hpp 

IEntryFieldN otifyHandler 

ientrynh.hpp 

IEnumHandle 

ihandle.hpp 

IErrorlnfo 

iexcept.hpp 

IEvent 

ievent.hpp 

IEventData 

ievtdata.hpp 

IEventParameter 1 

ievtdat2.hpp 

IEventParameter2 

ievtdat2.hpp 

IEventResult 

ievtdat2.hpp 

IException 

iexcbase.hpp 

Exception: :TraceFn 

iexcbase.hpp 

IExceptionLocation 

iexcbase.hpp 

IFileDialog 

ifiledlg.hpp 

IFileDialog:: Settings 

ifiledlg.hpp 

IFileDialog::Style 

ifiledlg.hpp 

IFileDialogEvent 

ifilehdr.hpp 

IFileDialogHandler 

ifilehdr.hpp 

IFlyOverHelpHandler 

iflyhhdr.hpp 

IFlyText 

iflytext.hpp 

IFocusHandler 

ifocshdr.hpp 

IFont 

ifont.hpp 

IFont: :FaceNameCursor 

ifont.hpp 

IFont: :PointSizeCursor 

ifont.hpp 

IFontDialog 

ifontdlg.hpp 

IFontDialog::Settings 

ifontdlg.hpp 

IFontDialog: :Style 

ifontdlg.hpp 
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Class Name 

Header File 

IFontDialogHandler 

ifonthdr.hpp 

IFrameEvent 

iframevt.hpp 

IFrameExtension 

iframext.hpp 

IFrameExtensions 

iframext.hpp 

IFrameFormatEvent 

iframevt.hpp 

IFrameHandler 

iframhdr.hpp 

IFrameWindow 

iframe.hpp 

IFrameWindow:: Style 

iframe.hpp 

IFrameW indowNotifyHandler 

iframnhd.hpp 

IG3PointArc 

igarc.hpp 

IGArc 

igarc.hpp 

IGBitmap 

igbitmap.hpp 

IGChord 

igpie.hpp 

IGEUipse 

igelipse.hpp 

IGLine 

igline.hpp 

IGList 

iglist.hpp 

IGList::Cursor 

iglist.hpp 

IGPie 

igpie.hpp 

IGPolygon 

igpyline.hpp 

IGPolyline 

igpyline.hpp 

IGRectangle 

igrect.hpp 

IGRegion 

igregion.hpp 

IGString 

igstring.hpp 

IGUIColor 

icolor.hpp 

IGUIErrorlnfo 

iexcept.hpp 

IGraphic 

igraphic.hpp 

IGraphicBundle 

igbundle.hpp 

IGraphicContext 

igrafctx.hpp 

IGraphicPushButton 

igraphbt.hpp 

IGraphicPushButton: :Style 

igraphbt.hpp 
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Class Name 

Header File 

IGroupBox 

igroupbx.hpp 

IGroupB ox:: Style 

igroupbx.hpp 

IHandle 

ibhandle.hpp 

IHandler 

ihandler.hpp 

IHelpErrorEvent 

ihelpevt.hpp 

IHelpHandler 

ihelphdr.hpp 

IHelpHyperlinkEvent 

ihelpevt.hpp 

IHelpMenuB arE vent 

ihelpevt.hpp 

IHelpNotifyEvent 

ihelpevt.hpp 

IHelpSubitemNotFoundEvent 

ihelpevt.hpp 

IHelpTutorialEvent 

ihelpevt.hpp 

IHelpWindow 

ihelp.hpp 

IHelpWindow:: Settings 

ihelp.hpp 

IHighEventParameter 

ievtdat2.hpp 

IlconControl 

iiconctl.hpp 

IlconControl:: Style 

iiconctl.hpp 

IlnfoArea 

iinfoa.hpp 

IlnvalidParameter 

iexcbase.hpp 

IlnvalidRequest 

iexcbase.hpp 

IKeyboardEvent 

ikeyevt.hpp 

IKeyboardHandler 

ikeyhdr.hpp 

IListBox 

ilistbox.hpp 

IListBox:: Style 

ilistbox.hpp 

ILi stB oxDra wltemE vent 

ilbdievt.hpp 

ILi stB oxDra wltemHandler 

ilbdihdr.hpp 

IListBoxNotifyHandler 

ilistbnh.hpp 

IListBoxSizeltemEvent 

ilbdievt.hpp 

ILowEventParameter 

ievtdat2.hpp 

IMM24FramesPerSecondTime 

immtime.hpp 

IMM25FramesPerSecondTime 

immtime.hpp 
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Class Name 

Header File 

IMM30FramesPerSecondTime 

immtime.hpp 

IMMAmpMixer 

immamix.hpp 

IMMAudioBuffer 

immabuf.hpp 

IMMAudioCD 

immcdda.hpp 

IMMAudioCDContents 

immcdda.hpp 

IMMAudioCDContents: :Cursor 

immcdda.hpp 

IMMCDXA 

immcdxa.hpp 

IMMConfigurableAudio 

immaud.hpp 

IMMCuePointEvent 

immevt.hpp 

IMMDevice 

immdev.hpp 

IMMDeviceEvent 

immevt.hpp 

IMMDeviceHandler 

immdvhdr.hpp 

IMMDigitalVideo 

immdigvd.hpp 

IMMErrorlnfo 

immexcpt.hpp 

IMMFileMedia 

immfilem.hpp 

IMMFIourMinS ecFrameT ime 

immtime.hpp 

IMMHourMinS ecTime 

immtime.hpp 

IMMMasterAudio 

immmaud.hpp 

IMMMillisecondTime 

immtime.hpp 

IMMMinSecFrameTime 

immtime.hpp 

IMMNotifyEvent 

immevt.hpp 

IMMPassDeviceEvent 

immevt.hpp 

IMMPlayableDevice 

immplayd.hpp 

IMMPlayerPanel 

immplypn.hpp 

IMMPlayerPanelFIandler 

immplyhd.hpp 

IMMPositionChangeEvent 

immevt.hpp 

IMMRecordable 

immrecrd.hpp 

IMMRemovableMedia 

immremed.hpp 

IMMRemovableMediaFlandler 

immremhd.hpp 

IMMSequencer 

immsequ.hpp 
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Class Name 

Header File 

IMMSpeed 

immspeed.hpp 

IMMTime 

immtime.hpp 

IMMTrackMinSecFrameTime 

immttime.hpp 

IMMW ave Audio 

immwave.hpp 

IMenu 

imenu.hpp 

IMenu::Cursor 

imenu.hpp 

IMenu::Style 

imenu.hpp 

IMenuBar 

imenubar.hpp 

IMenuBar::Style 

imenubar.hpp 

IMenuDrawItemEvent 

imndievt.hpp 

IMenuDrawItemHandler 

imndihdr.hpp 

IMenuDrawItemHandler: :DrawFlag 

imndihdr.hpp 

IMenuEvent 

imenuevt.hpp 

IMenuHandle 

ihandle.hpp 

IMenuHandler 

imenuhdr.hpp 

IMenuItem 

imnitem.hpp 

IMenuItem:: Attribute 

imnitem.hpp 

IMenuItem:: Style 

imnitem.hpp 

IMenuNotifyHandler 

imenunhd.hpp 

IMessageBox 

imsgbox.hpp 

IMessageBox::Style 

imsgbox.hpp 

IMessageQueueHandle 

ihandle.hpp 

IMessageText 

imsgtext.hpp 

IMngElemPointer 

iptr.h 

IMngPointer 

iptr.h 

IModuleHandle 

ihandle.hpp 

IMouseClickEvent 

imousevt.hpp 

IMouseEvent 

imousevt.hpp 

IMouseHandler 

imoushdr.hpp 

IMousePointerEvent 

imousevt.hpp 
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Class Name 

Header File 

IMousePointerHandler 

imphdr.hpp 

IMultiCellCanvas 

imcelcv.hpp 

IMultiCellCanvas:: Style 

imcelcv.hpp 

IMultiLineEdit 

imle.hpp 

IMultiLineEdit: :Style 

imle.hpp 

IMultiLineEditNotifyHandler 

imlenhdr.hpp 

INotebook 

inotebk.hpp 

INotebook:: Cursor 

inotebk.hpp 

INotebook: :PageSettings 

inotebk.hpp 

INotebook: :PageSettings:: Attribute 

inotebk.hpp 

INotebook::Style 

inotebk.hpp 

INotebookDrawItemEvent 

inbdievt.hpp 

IN otebookN otify Handler 

inotebnh.hpp 

INotificationEvent 

inotifev.hpp 

INotifier 

inotify.hpp 

INumericSpinButton 

ispinnum.hpp 

INumericSpinButton:: Style 

ispinnum.hpp 

INumericSpinButtonNotify Handler 

ispbtnnh.hpp 

IObjectWindow 

iobjwin.hpp 

IObserver 

iobservr.hpp 

IObserverList 

iobslist.hpp 

IObserverList: :Cursor 

iobslist.hpp 

IOutOfMemory 

iexcbase.hpp 

IOutOfSystemResource 

iexcbase.hpp 

IOutOfWindowResource 

iexcbase.hpp 

IOutlineBox 

ioutlbox.hpp 

IOutlineBox:: Style 

ioutlbox.hpp 

IPageEvent 

ipageevt.hpp 

IPageHandle 

inotebk.hpp 

IPageHandler 

ipagehdr.hpp 
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Class Name 

Header File 

IPageHelpEvent 

ipageevt.hpp 

IPageRemoveEvent 

ipageevt.hpp 

IPageSelectEvent 

ipageevt.hpp 

IPaintEvent 

ipainevt.hpp 

IPaintHandler 

ipainhdr.hpp 

IPair 

ipoint.hpp 

IPoint 

ipoint.hpp 

IPointArray 

iptarray.hpp 

IPointerHandle 

ihandle.hpp 

IPopUpMenu 

ipopmenu.hpp 

IPresSpaceHandle 

ihandle.hpp 

IPrivateResource 

ireslock.hpp 

IProcedureAddress 

iprocadr.hpp 

IProcessId 

ihandle.hpp 

IProfile 

iprofile.hpp 

IProfile:: Cursor 

iprofile.hpp 

IProfileHandle 

ihandle.hpp 

IProgressIndicator 

islider.hpp 

IProgressIndicator:: Style 

islider.hpp 

IPushButton 

ipushbut.hpp 

IPushButton::Style 

ipushbut.hpp 

IRadioButton 

iradiobt.hpp 

IRadioB utton:: S ty le 

iradiobt.hpp 

IRange 

ipoint.hpp 

IRectangle 

irect.hpp 

IRefCounted 

irefcnt.hpp 

IReference 

irefcnt.hpp 

IRegionHandle 

ihandle.hpp 

IResizeEvent 

isizeevt.hpp 

IResizeHandler 

isizehdr.hpp 


© IBM Corp. 1992, 1995 


Appendix G. Classes and Header Files Cross-Reference 1327 



Class Name 

Header File 

IResource 

ire slock, hpp 

IResourceExhausted 

iexcbase.hpp 

IResourceld 

ireslib.hpp 

IResourceLibrary 

ireslib.hpp 

IResourceLock 

ireslock.hpp 

ISWP 

iswp.hpp 

ISWP Array 

iswp.hpp 

IScrollBar 

iscroll.hpp 

IScrollBar::Style 

iscroll.hpp 

IScrollB arNotifyHandler 

isclnhdr.hpp 

IScrollEvent 

iscrlevt.hpp 

IScrollHandler 

iscrlhdr.hpp 

ISelectHandler 

iselhdr.hpp 

ISemaphoreHandle 

ibhandle.hpp 

ISetCanvas 

isetcv.hpp 

ISetCanvas:: Style 

isetcv.hpp 

ISettingButton 

isetbut.hpp 

ISettingButtonNotifyHandler 

isetbnhd.hpp 

ISharedResource 

ireslock.hpp 

IShowListHandler 

islhdr.hpp 

ISize 

ipoint.hpp 

ISlider 

islider.hpp 

ISlider::Style 

islider.hpp 

ISliderArmHandler 

isldahdr.hpp 

ISliderDrawHandler 

islidhdr.hpp 

ISpinHandler 

ispinhdr.hpp 

ISplitCanvas 

isplitcv.hpp 

ISplitCanvas:: Style 

isplitcv.hpp 

IS tandardN otifier 

istdntfy.hpp 

IStaticText 

istattxt.hpp 
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Class Name 

Header File 

IStaticText:: Style 

istattxt.hpp 

IString 

istring.hpp 

IStringEnum 

istrenum.hpp 

IStringGenerator 

istrgen.hpp 

IStringGeneratorFn 

istrgen.hpp 

IStringGeneratorMemberFn 

istrgen.hpp 

IStringGeneratorRelMemberFn 

istrgen.hpp 

IStringHandle 

ihandle.hpp 

IStringParser 

istparse.hpp 

IStringParser:: SkipWords 

istparse.hpp 

IStringTest 

istrtest.hpp 

IStringTestMemberFn 

istrtest.hpp 

ISubmenu 

isubmenu.hpp 

ISubmenu: :Cursor 

isubmenu.hpp 

ISystemBitmapHandle 

ihandle.hpp 

ISystemErrorlnfo 

iexcept.hpp 

ISystemMenu 

isysmenu.hpp 

ISystemPointerHandle 

ihandle.hpp 

ITextControl 

itextctl.hpp 

ITextControlNotifyHandler 

itextcnh.hpp 

ITextSpinButton 

ispintxt.hpp 

ITextSpinButton: :Cursor 

ispintxt.hpp 

ITextSpinButton: :Style 

ispintxt.hpp 

ITextSpinButtonNotifyHandler 

ispbttnh.hpp 

IThread 

ithread.hpp 

IThread::Cursor 

ithread.hpp 

IThreadFn 

ithread.hpp 

IThreadld 

ihandle.hpp 

IThreadMemberFn 

ithread.hpp 

ITime 

itime.hpp 
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Class Name 

Header File 

ITimer 

itimer.hpp 

ITimer::Cursor 

itimer.hpp 

ITimerFn 

itimer.hpp 

ITimerMemberFn 

itimer.hpp 

ITimerMemberFnO 

itimer.hpp 

ITitle 

ititle.hpp 

ITitleNotifyFlandler 

ititlenh.hpp 

IToolBar 

itbar.hpp 

IToolB ar:: FrameCursor 

itbar.hpp 

IToolBar:: Style 

itbar.hpp 

IToolB ar:: Windo wCursor 

itbar.hpp 

IToolB arButton 

itbarbut.hpp 

IT oolB arButton:: Style 

itbarbut.hpp 

IT oolB arContainer 

itbarcnr.hpp 

IT oolB arContainer:: Style 

itbarcnr.hpp 

IToolB arFrame W indo w 

itbarfrm.hpp 

ITrace 

itrace.hpp 

ITransformMatrix 

itrnsfrm.hpp 

IVBase 

ivbase.hpp 

I ViewPort 

ivport.hpp 

IViewPort::Style 

ivport.hpp 

IWindow 

iwindow.hpp 

IWindow::BidiSettings 

iwindow.hpp 

IWindow:: ChildCursor 

iwindow.hpp 

IWindow::ExceptionFn 

iwindow.hpp 

IWindow::Style 

iwindow.hpp 

IWindowFIandle 

ihandle.hpp 

IW indowNotifyHandler 

iwinnhdr.hpp 

IXLibErrorlnfo 

iexcept.hpp 

Iterator 

iiter.h 
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Class Name 

Header File 

Key Bag 

ikeybag.h 

Key Collection 

iakey.h 

Key Set 

ikeyset.h 

Key Sorted Bag 

iksbag.h 

Key Sorted Collection 

iaksrt.h 

Key Sorted Set 

iksset.h 

Manipulators 

iomanip.h 

Map 

imap.h 

Ordered Collection 

iaorder.h 

Pointer Classes 

iptr.h 

Priority Queue 

iprioqu.h 

Queue 

iqueue.h 

Relation 

irel.h 

Sequence 

iseq.h 

Sequential Collection 

iasqntl.h 

Set 

iset.h 

Sorted Bag 

isrtbag.h 

Sorted Collection 

iasrt.h 

Sorted Map 

isrtmap.h 

Sorted Relation 

isrtrel.h 

Sorted Set 

isrtset.h 

Stack 

istack.h 

Tree 

itree.h 

Tree Cursor 

itcursor.h 

c_exception 

complex.h 

complex 

complex.h 

filebuf 

fstream.h 

fstream 

fstream.h 

fstreambase 

fstream.h 

ifstream 

fstream.h 
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Class Name 

Header File 

ios 

iostream.h 

iostream 

iostream.h 

iostream_withassign 

iostream.h 

istream 

iostream.h 

istream_withassign 

iostream.h 

istrstream 

iostream.h 

ofstream 

fstream.h 

ostream 

iostream.h 

ostream_withassign 

iostream.h 

ostrstream 

iostream.h 

stdiobuf 

stdiostream.h 

stdiostream 

stdiostream.h 

streambuf 

iostream.h 

strstream 

iostream.h 

strstreambase 

iostream.h 

strstreambuf 

strstream.h 
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Header Files to Classes 

The following table shows the classes that are in a specific header file. 


Header File 

Classes 

complex.h 

c_exception 


complex 


fstream.h filebuf 

fstream 

fstreambase 


ifstream 

ofstream 


iOstring.hpp 

IOString 

i3statbx.hpp 

I3StateCheckBox::Style 

I3StateCheckBox 

iaccel.hpp 

IAccelerator 

iacllct.h 

Collection 

iaeqkey.h 

Equality Key Collection 

iaeqksrt.h 

Equality Key Sorted Collection 

iaeqsrt.h 

Equality Sorted Collection 

iaequal.h 

Equality Collection 

iakey.h 

Key Collection 

iaksrt.h 

Key Sorted Collection 

ianimbut.hpp 

IAnimatedButton::Style 

IAnimatedButton 

iaorder.h 

Ordered Collection 

iapp.hpp 

IApplication 

ICurrentApplication 

iasqntl.h 

Sequential Collection 

iasrt.h 

Sorted Collection 

ibag.h 

Bag 

ibase.hpp 

IB ase:: Version 

IBase 

ibhandle.hpp 

Handle 

ISemaphoreHandle 

ibitflag.hpp 

IBitFlag 
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Header File 

Classes 

ibmpctl.hpp 

IBitmapControl::Style 

IBitmapControl 

ibtnnhdr.hpp 

IButtonNotifyHandler 

ibuffer.hpp 

IBuffer 

ibutton.hpp 

IButton 

IButton::Style 

icanvas.hpp 

ICanvas::Style 

ICanvas 

icheckbx.hpp 

ICheckBox::Style 

ICheckBox 

iclipbrd.hpp 

IClipboard "Cursor 

IClipboard 

icliphdr.hpp 

IClipboardHandler 

icmdevt.hpp 

ICommandEvent 

icmdhdr.hpp 

ICommandHandler 

icnrclst.hpp 

ICnrControlList 

icnrcol.hpp 

IContainerColumn 

icnrctl.hpp 

IContainerControl: :ObjectCursor 
IContainerControl: :Style 

IContainerControl: :TextCursor 

IContainerControl 

IContainerControl:: Attribute 

IContainerControl: :ColumnCursor 
IContainerControl: :CompareFn 
IContainerControl: :FilterFn 

IContainerControl: iterator 

icnrdiev.hpp 

ICnrDrawItemEvent 

ICnrDrawB ackgroundEvent 

icnrdihd.hpp 

ICnrDrawHandler 

icnreevt.hpp 

ICnrReallocStringEvent 

ICnrBeginEditEvent 

ICnrEditEvent 

ICnrEndEditEvent 

icnrehdr.hpp 

ICnrEditHandler 
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Header File 

Classes 

icnrevt.hpp 

ICnrQueryDeltaEvent 

ICnrEmphasisEvent 

ICnrScrollEvent 

ICnrEnterEvent 

ICnrEvent 

ICnrHelpEvent 

icnrhdr.hpp 

ICnrHandler 

icnrmhdr.hpp 

ICnrMenuHandler 

icnrnhdr.hpp 

IContainerControlNotifyHandler 

icnrobj.hpp 

IContainerObject 

ICnrAllocator 

icnrolst.hpp 

ICnrObjectSet 

icollvwi.hpp 

ICollectionViewConstants 

icolor.hpp 

IGUIColor 

IColor 

IDeviceColor 

icombobs.hpp 

IBaseComboBox 

IBaseComboBox: :Cursor 

IBaseComboBox: :Style 

icombobx.hpp 

IComboBox:: Style 

IComboBox 

icombonh.hpp 

IComboBoxNotifyHandler 

icombovw.hpp 

ICollectionViewComboBox 

icontrol.hpp 

IControl::Style 

IControl 

icoordsy.hpp 

ICoordinateSystem 

icritsec.hpp 

ICritSec 

icsliden.hpp 

ICircularSliderNotifyHandler 

icslider.hpp 

ICircularSlider 

ICircularSlider:: Style 

ictlevt.hpp 

IControlEvent 

icursor.h 

Cursor 

icustbev.hpp 

ICustomButtonDrawEvent 

icustbhd.hpp 

ICustomButtonDrawHandler 
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Header File 

Classes 

icustbut.hpp 

ICustomButton 

ICustomButton::Style 

idate.hpp 

IDate 

idbcsbuf.hpp 

IDBCSBuffer 

iddeccnv.hpp 

IDDEClientConversation 

iddecomm.hpp 

IDDE 

iddecset.hpp 

IDDEClientHotLinkSet 

IDDEActiveServerSet 

IDDEActiveServer 

iddeevt.hpp 

IDDEBeginEvent 

IDDEClientAcknowledgeEvent 

IDDEAcknowledgePokeEvent 

IDDEClientEndEvent 

IDDEClientHotLinkEvent 

IDDEAcknowledgeEvent 

IDDEDataEvent 

IDDEEndEvent 

IDDEEvent 

IDDEExecuteEvent 

IDDEPokeEvent 

IDDERequestDataEvent 

IDDEServerAcknowledgeEvent 

IDDEServerHotLinkEvent 

IDDESetAcknowledgelnfoEvent 

IDDEAcknowledgeExecuteEvent 

iddetsrv.hpp 

IDDETopicServer 

ideque.h 

Deque 

idievt.hpp 

IDrawItemEvent 

idmcnrit.hpp 

IDMCnrltem 

idmcomm.hpp 

IDM 

idmefit.hpp 

IDMEFItem 
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Header File 

Classes 

idmevent.hpp 

IDMSourcePrintEvent 

IDMSourceRenderEvent 

IDMT argetDropE vent 

IDMT argetEndE vent 

IDMT argetEnterE vent 

IDMT argetE vent 

IDMTargetHelpEvent 

IDMT argetLeaveEvent 

IDMEvent 

IDMSourceBeginEvent 

IDMSourceDiscardEvent 

IDMSourceEndEvent 

IDMSourcePrepareEvent 

idmhndlr.hpp 

IDMHandler 

idmimage.hpp 

IDMImage 

IDMImage:: Style 

idmitem.hpp 

IDMItem 

idmmenit.hpp 

IDMMenuItem 

idmmleit.hpp 

IDMMLEItem 

idmoper.hpp 

IDMOperation 

idmprov.hpp 

IDMItemProviderFor 

IDMItemProvider 

idmrendr.hpp 

IDMRenderer 

idmsrch.hpp 

IDMSourceHandler 

idmsrcop.hpp 

IDMSoureeOperation 

idmsrcrn.hpp 

IDMSourceRenderer 

idmtbbit.hpp 

IDMTB arB uttonltem 

idmtbrit.hpp 

IDMT oolB arltem 

idmtgth.hpp 

IDMT argetHandler 

idmtgtop.hpp 

IDMT argetOperation 

idmtgtrn.hpp 

IDMT argetRenderer 

idrawcv.hpp 

IDrawingCanvas: :Style 

IDrawingCanvas 

iedithdr.hpp 

IEditHandler 

ientryfd.hpp 

IEntryField::Style 

IEntryField 
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Header File 

Classes 

ientrynh.hpp 

IEntryFieldNotifyHandler 

ieqseq.h 

Equality Sequence 

ievent.hpp 

IEvent 

ievtdat2.hpp 

IHighEventParameter 

ILowEventParameter 

IEventResult 

IEventParameter 1 

IEventParameter2 

ievtdata.hpp 

IEventData 

iexcbase.hpp 

IExceptionLocation 

IAccessError 

IAssertionFailure 

IDeviceError 

IlnvalidParameter 

IlnvalidRequest 

IException 

IOutOfMemory 

IOutOfSystemResource 

IOutOfWindowResource 

IResourceExhausted 

IException: :TraceFn 

iexcept.hpp 

IErroiInfo 

ISystemErrorlnfo 

IXLibErrorlnfo 

ICLibErrorlnfo 

IGUIErrorlnfo 

ifiledlg.hpp 

IFileDialog::Style 

IFileDialog 

IFileDialog::Settings 

ifilehdr.hpp 

IFileDialogEvent 

IFileDialogHandler 

iflyhhdr.hpp 

IFlyOverHelpHandler 

iflytext.hpp 

IFlyText 

ifocshdr.hpp 

IFocusHandler 

ifont.hpp 

IFont: :PointSizeCursor 

IFont 

IFont: :FaceNameCursor 
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Header File 

Classes 

ifontdlg.hpp 

IFontDialog: :Style 

IFontDialog 

IFontDialog:: Settings 

ifonthdr.hpp 

IFontDialogHandler 

iframe.hpp 

IFrameWindow 

IFrame Window:: Style 

iframevt.hpp 

IFrameEvent 

IFrameFormatEvent 

iframext.hpp 

IFrameExtensions 

IFrameExtension 

iframhdr.hpp 

IFrameHandler 

iframnhd.hpp 

IFrameWindowNotifyHandler 

igarc.hpp 

IG3PointArc 

IGArc 

igbitmap.hpp 

IGBitmap 

igbundle.hpp 

IGraphicBundle 

igelipse.hpp 

IGEllipse 

igline.hpp 

IGLine 

iglist.hpp 

IGList::Cursor 

IGList 

igpie.hpp 

IGPie 

IGChord 

igpyline.hpp 

IGPolyline 

IGPolygon 

igrafctx.hpp 

IGraphicContext 

igraphbt.hpp 

IGraphicPushButton 

IGraphicPushButton: :Style 

igraphic.hpp 

IGraphic 

igrect.hpp 

IGRectangle 

igregion.hpp 

IGRegion 

igroupbx.hpp 

IGroupBox 

IGroupB ox:: S ty le 

igstring.hpp 

IGString 
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Header File 

Classes 

ihandle.hpp 

IStringHandle 

ISy stemB itmapHandle 

IEnumHandle 

ISystemPointerHandle 

IThreadld 

IW indo wHandle 

IMenuHandle 

IMessageQueueHandle 

IModuleHandle 

IAccelTblHandle 

IAnchorBlockHandle 

IDisplayHandle 

IPointerHandle 

IPresSpaceHandle 

IProcessId 

IProfileHandle 

IRegionHandle 

IB itmapHandle 

IContextHandle 

ihandler.hpp 

IHandler 

iheap.h 

Heap 

ihelp.hpp 

IHelp Window 

IHelpWindow:: Settings 

ihelpevt.hpp 

IHelpMenuB arEvent 

IHelpNotifyEvent 

IHelpSubitemNotFoundEvent 

IHelpTutorialEvent 

IHelpErrorEvent 

IHelpHyperlinkEvent 

ihelphdr.hpp 

IHelpHandler 

iiconctl.hpp 

IlconControl: :Style 

IlconControl 

iinfoa.hpp 

IlnfoArea 

iiter.h 

Constant Iterator 

Iterator 

ikeybag.h 

Key Bag 

ikeyevt.hpp 

IKeyboardEvent 

ikeyhdr.hpp 

IKeyboardHandler 

ikeyset.h 

Key Set 
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iksbag.h 

Key Sorted Bag 

iksset.h 

Key Sorted Set 

ilbdievt.hpp 

IListBoxDrawItemEvent 

IListBoxSizeltemEvent 

ilbdihdr.hpp 

IListBoxDrawItemHandler 

ilistbas.hpp 

IBaseListBox: :Cursor 

IBaseListBox::Style 

IBaseListBox 

ilistbnh.hpp 

ILi stB oxNotify Handler 

ilistbox.hpp 

IListBox 

IListBox::Style 

ilistcvw.hpp 

ICollectionViewListBox 

imap.h 

Map 

imcelcv.hpp 

IMultiCellCanvas:: Style 

IMultiCellCanvas 

imenu.hpp 

IMenu::Cursor 

IMenu:: Style 

IMenu 

imenubar.hpp 

IMenuBar 

IMenuBar::Style 

imenuevt.hpp 

IMenuEvent 

imenuhdr.hpp 

IMenuHandler 

imenunhd.hpp 

IMenuNotify Handler 

imle.hpp 

IMultiLineEdit: :Style 

IMultiLineEdit 

imlenhdr.hpp 

IMultiLineEditNotifyHandler 

immabuf.hpp 

IMM AudioB uffer 

immamix.hpp 

IMMAmpMixer 

immaud.hpp 

IMMConfigurableAudio 

immcdda.hpp 

IMMAudioCDContents 
IMMAudioCDContents: :Cursor 

IMMAudioCD 

immcdxa.hpp 

IMMCDXA 

immdev.hpp 

IMMDevice 
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immdigvd.hpp 

IMMDigitalVideo 

immdvhdr.hpp 

IMMDeviceHandler 

immevt.hpp 

IMMDeviceEvent 

IMMNotifyEvent 

IMMPassDeviceEvent 

IMMPositionChangeEvent 

IMMCuePointEvent 

immexcpt.hpp 

IMMErrorlnfo 

immfilem.hpp 

IMMFileMedia 

immmaud.hpp 

IMMMasterAudio 

immplayd.hpp 

IMMPlayableDevice 

immplyhd.hpp 

IMMPlayerPanelHandler 

immplypn.hpp 

IMMPlayerPanel 

immrecrd.hpp 

IMMRecordable 

immremed.hpp 

IMMRemovableMedia 

immremhd.hpp 

IMMRemovableMediaHandler 

immsequ.hpp 

IMMSequencer 

immspeed.hpp 

IMMSpeed 

immtime.hpp 

IMM24FramesPerSecondTime 

IMM25FramesPerSecondTime 

IMMHourMinSecFrameTime 

IMMHourMinSecTime 

IMMTime 

IMM30FramesPerSecondTime 

IMMMillisecondTime 

IMMMinSecFrameTime 

immttime.hpp 

IMMTrackMinSecFrameTime 

immwave.hpp 

IMMW ave Audio 

imndievt.hpp 

IMenuDrawItemEvent 

imndihdr.hpp 

IMenuDrawItemHandler 
IMenuDrawItemHandler: :DrawFlag 

imnitem.hpp 

IMenuItem:: Attribute 

IMenuItem:: Style 

IMenuItem 
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imousevt.hpp 

IMouseEvent 

IMousePointerEvent 

IMouseClickEvent 

imoushdr.hpp 

IMouseHandler 

imphdr.hpp 

IMousePointerHandler 

imsgbox.hpp 

IMessageBox::Style 

IMessageBox 

imsgtext.hpp 

IMessageText 

inbdievt.hpp 

INotebookDrawItemEvent 

inotebk.hpp 

INotebook: :Cursor 

INotebook: :PageSettings 

INotebook: :PageSettings:: Attribute 
IPageHandle 

INotebook: :Style 

INotebook 

inotebnh.hpp 

IN otebookN otify Handler 

inotifev.hpp 

INotificationEvent 

inotify.hpp 

INotifier 

iobjwin.hpp 

IObjectWindow 

iobservr.hpp 

IObserver 

iobslist.hpp 

IObserverList 

IObserverList: :Cursor 

iomanip.h 

Manipulators 

iostream.h 

iostream 

iostream_withassign 

istream 

istream_withassign 

istrstream 

ios 

ostream 

ostream_withassign 

ostrstream 

streambuf 

strstream 

strstreambase 

ioutlbox.hpp 

IOutlineBox 

IOutlineBox:: Style 
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Header File 
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ipageevt.hpp 

IPageHelpEvent 

IPageRemoveEvent 

IPageSelectEvent 

IPageEvent 

ipagehdr.hpp 

IPageHandler 

ipainevt.hpp 

IPaintEvent 

ipainhdr.hpp 

IPaintHandler 

ipoint.hpp 

IRange 

ISize 

IPair 

IPoint 

ipopmenu.hpp 

IPopUpMenu 

iprioqu.h 

Priority Queue 

iprocadr.hpp 

IProcedureAddress 

iprofile.hpp 

IProfile:: Cursor 

IProfile 

iptarray.hpp 

IPointArray 

iptr.h 

IMngPointer 

Pointer Classes 

IElemPointer 

IAutoElemPointer 

IAutoPointer 

IMngElemPointer 

ipushbut.hpp 

IPushButton:: Style 

IPushButton 

iqueue.h 

Queue 

iradiobt.hpp 

IRadioButton 

IRadioButton: :Style 

irect.hpp 

IRectangle 

irefcnt.hpp 

IReference 

IRefCounted 

irel.h 

Relation 

ireslib.hpp 

IResourceLibrary 

IDynamicLinkLibrary 

IResourceld 
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ireslock.hpp 

ISharedResource 

IPrivateResource 

IResourceLock 

IResource 

isclnhdr.hpp 

IScrollBarNotifyHandler 

iscrlevt.hpp 

IScrollEvent 

iscrlhdr.hpp 

IScrollHandler 

iscroll.hpp 

IScrollBar 

IScrollBar::Style 

iselhdr.hpp 

ISelectHandler 

iseq.h 

Sequence 

iset.h 

Set 

isetbnhd.hpp 

ISettingButtonNotifyHandler 

isetbut.hpp 

ISettingButton 

isetcv.hpp 

ISetCanvas 

ISetCanvas::Style 

isizeevt.hpp 

IResizeEvent 

isizehdr.hpp 

IResizeHandler 

isldahdr.hpp 

ISliderArmHandler 

islhdr.hpp 

IShowListHandler 

islider.hpp 

IProgressIndicator: :Style 

ISlider 

ISlider::Style 

IProgressIndicator 

islidhdr.hpp 

ISliderDrawHandler 

ispbtnnh.hpp 

INumericSpinButtonNotifyHandler 

ispbttnh.hpp 

ITextSpinButtonNotifyHandler 

ispinbas.hpp 

IBaseSpinButton::Style 

IBaseSpinButton 

ispinhdr.hpp 

ISpinHandler 

ispinnum.hpp 

INumericSpinButton 

INumericSpinButton:: Style 
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ispintxt.hpp 

ITextSpinB utton:: S ty le 

ITextSpinB utton 

ITextSpinButton: :Cursor 

isplitcv.hpp 

ISplitCanvas 

ISplitCanvas:: Style 

isrtbag.h 

Sorted Bag 

isrtmap.h 

Sorted Map 

isrtrel.h 

Sorted Relation 

isrtset.h 

Sorted Set 

istack.h 

Stack 

istattxt.hpp 

IStaticText::Style 

IStaticText 

istdntfy.hpp 

IStandardNotifier 

istparse.hpp 

IStringParser 

IStringParser: :SkipWords 

istrenum.hpp 

IStringEnum 

istrgen.hpp 

IStringGeneratorRefMemberFn 

IStringGenerator 

IStringGeneratorFn 

IStringGeneratorMemberFn 

istring.hpp 

IString 

istrtest.hpp 

IStringTest 

IStringTestMemberFn 

isubmenu.hpp 

ISubmenu 

ISubmenu: :Cursor 

iswp.hpp 

ISWP Array 

ISWP 

isysmenu.hpp 

ISystemMenu 

itbar.hpp 

IToolBar 

IToolB ar:: FrameCursor 

IToolBar::Style 

IToolB ar:: W indo wCursor 

itbarbut.hpp 

IToolBarButton 

IToolBarButton::Style 

itbarcnr.hpp 

IToolB arContainer 

IT oolB arContainer:: Style 
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itbarfrm.hpp 

IToolB arFrame W indo w 

itcursor.h 

Tree Cursor 

itextcnh.hpp 

ITextControlNotifyHandler 

itextctl.hpp 

ITextControl 

ithread.hpp 

ICurrentThread 

IThread::Cursor 

IThreadFn 

IThread 

IThreadMemberFn 

itime.hpp 

ITime 

itimer.hpp 

ITimer 

ITimer::Cursor 

ITimerFn 

ITimerMemberFn 

ITimerMemberFnO 

ititle.hpp 

ITitle 

ititlenh.hpp 

ITitleNotifyHandler 

itrace.hpp 

ITrace 

itree.h 

Tree 

itrnsfrm.hpp 

ITransformMatrix 

ivbase.hpp 

IVBase 

ivport.hpp 

IViewPort::Style 

IViewPort 

iwindow.hpp 

IWindow:: ChildCursor 

IWindow::ExceptionFn 

IWindow::Style 

IWindow::BidiSettings 

IWindow 

iwinnhdr.hpp 

IW indo wNotify Handler 

stdiostream.h 

stdiostream 

stdiobuf 

strstream.h 

strstreambuf 
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abstract class ‘audio track 


Glossary 


This glossary defines terms and abbreviations that are used in 
this book. If you do not find the term you are looking for, 
refer to the IBM Dictionary of Computing, New 
York:McGraw-Hill, 1994. 

This glossary includes terms and definitions from the 
American National Standard Dictionary for Information 
Systems, ANSI X3.172-1990, copyright 1990 by the 
American National Standards Institute (ANSI). Copies may 
be purchased from the American National Standards Institute, 
1430 Broadway, New York, New York 10018. 


A 

abstract class. (1) A class with at least one pure virtual 
function that is used as a base class for other classes. The 
abstract class represents a concept; classes derived from it 
represent implementations of the concept. You cannot 
construct an object of an abstract class. See also base class. 
(2) A class that allows polymorphism. 

abstract data type. A mathematical model that includes a 
structure for storing data and operations that can be 
performed on that data. Common abstract data types include 
sets, trees, and heaps. 

abstraction (data). See data abstraction. 

access. An attribute that determines whether or not a class 
member is accessible in an expression or declaration. It can 
be public, protected, or private. 

access declaration. A declaration used to adjust access to 
members of a base class. 

access function. A function that returns information about 
the elements of an object so that you can analyze various 
elements of a string. 

access resolution. The process by which the accessibility of 
a particular class member is determined. 

access specifier. One of the C++ keywords public, private, 
or protected. 

ambiguous derivation. A derivation where the class is 
derived from two or more base classes that have members 
with the same name. 


amplifier. A device that increases the strength of input 
signals. Also referred to as an amp. 

amplifier-mixer. A combination amplifier and mixer that is 
used to control the characters of an audio signal from one or 
more audio sources. Also referred to as an amp-mixer. 

animate. Make or design in such a way as to create 
apparently spontaneous, lifelike movement. 

animation rate. The number of thousandths of a second that 
pass before the next bitmap is displayed for a button while it 
is animated. 

anonymous union. A union that is declared within a 
structure or class and that does not have a name. 

area. In computer graphics, a filled shape, such as a solid 
rectangle. 

array. An aggregate that consists of data objects, with 
identical attributes, each of which may be uniquely referenced 
by subscripting. 

array implementation. (In Collection Class Library) 
Implementation of an abstract data type using an array. Also 
called a tabular implementation. 

ASCII (American National Standard Code for 
Information Interchange). The standard code, using a 
coded character set consisting of 7-bit coded characters (8 
bits including parity check), that is used for information 
interchange among data processing systems, data 
communication systems, and associated equipment. The 
ASCII set consists of control characters and graphic 
characters. 

Note: IBM has defined an extension to ASCII code 
(characters 128-255). 

audio. Pertaining to the portion of recorded information that 
can be heard. 

audio attributes. The standard audio attributes are: mute, 
volume, balance, treble, and bass. 

audio formats. The way the audio information is stored and 
interpreted. 

audio track. (1) The audio (sound) portion of the program. 
(2) The physical location where the audio is places beside the 
image. (A system with two sound tracks can have either 
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stereo sound or two independent sound tracks.) Synonymous 
with sound track. 

automatic storage. Storage that is allocated on entry to a 
routine or block and is freed on the subsequent return. 
Sometimes referred to as stack storage or dynamic storage. 

automatic storage management. The process that 
automatically allocates and deallocates objects in order to use 
memory efficiently. 

auxiliary classes. Classes that support other classes. 
Auxiliary classes in the Collection Class Library include 
classes for cursors, pointers and iterators. 

AVL tree. A balanced binary search tree that does not allow 
the height of two siblings to differ by more than one. 

B 

B*-tree (B star tree). A tree in which only the leaves 
contain whole elements. All other nodes contain keys. 

background color. The color in which the background of a 
graphic primitive is drawn. 

balance. (1) For audio, refers to the relative strength of the 
left and right channels. A balance level of 0 is left channel 
only. A balance level of 100 is right channel only (2) A 
state of equilibrium, usually between treble and bass. 

base class. A class from which other classes are derived. A 
base class may itself be derived from another base class. See 
also abstract class. 

based on. A relationship between two classes in which one 
class is implemented through the other. A new class is 
“based on” an existing class when the existing class is used 
to implement it. 

bass. The lower half of the whole vocal or instrumental 
tonal range. 

bit field. A member of a structure or union that contains a 
specified number of bits. 

bit mask. A pattern of characters used to control the 
retention or elimination of portions of another patterns of 
characters. 

bits-per-sample. The number of bits of audio data that is to 
represent each sample of each channel (right or left). This is 
the resolution of the audio data. CD quality needs to be 16 
bits-per-sample. 


boundary alignment. The position in main storage of a 
fixed-length field (such as byte or doubleword) on an integral 
boundary for that unit of information. 

For the Class Library example, a word boundary is a storage 
address evenly divisible by two. 

bounded collection. A collection that has an upper limit on 
the number of elements it can contain. 

brightness. The level of luminosity of the video signal. A 
brightness level of 0 produces a maximally white signal. A 
brightness level of 100 produces a maximally black signal. 

built-in. A function that the compiler automatically puts 
inline instead of generating a call to the function. 

C 

camcorder. A compact, hand-held video camera with 
integrated videotape recorder. 

canvas. Canvases are windows with a layout algorithm that 
manage child windows. The canvas classes are a set of 
window classes which allow you to implement dialog-like 
windows (that is, a window with several child controls). 

These windows are used for showing views of objects as both 
pages in a notebook and as windows that gather information 
to run an action. The different canvases can manage the size 
and position of child windows, provide moveable split bars 
between windows, and support the ability to scroll a window. 

The canvases include the base class, ICanvas, and its four 
derived classes: IMultiCellCanvas, ISetCanvas, ISplitCanvas, 
and I Viewport. 

cast. A notation used to express the conversion of one type 
to another. 

catch block. A block associated with a try block that 
receives control when a C++ exception matching its argument 
is thrown. 

CD. Compact disc 

CD-ROM. Compact disc-read-only memory 

CD-XA. Compact disc-extended architecture 

channel mapping. The translation of a MIDI channel 
number for a sending device to an appropriate channel for a 
receiving device. 

character array. An array of type char. 
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child. A node that is subordinate to another node in a tree 
structure. Only the root node of a tree is not a child. 

child class. See derived class. 

child window. A window derived from another window and 
drawn relative to it. 

circular slider control. A 360-degree knob-like control that 
simulates the buttons on a TV, a stereo, or video components. 
By rotating the slider arm, the user can set, display, or 
modify a value, such as the balance, bass, volume, or treble. 

class. A user-defined type. Classes can be defined 
hierarchically, allowing one class to be an expansion of 
another, and classes can restrict access to their members. 

class hierarchy. A tree-like structure showing relationships 
among classes. It places one abstract class at the top (a base 
class) and one or more layers of derived classes below it. 

class library. A collection of classes. 

class template. A blueprint describing how a set of related 
classes can be constructed. 

client area window. An intermediate window between an 
IFrameWindow and its controls and other child windows. 

client program. A program that uses a class. The program 
is said to be a client of the class. 

collection. (1) In a general sense, an implementation of an 
abstract data type for storing elements. (2) An abstract class 
without any ordering, element properties, or key properties. 
All abstract Collection Classes are derived from Collection. 

Collection Classes. A set of classes that implement abstract 
data types for storing elements. 

color palette. A set of all the colors that can be used in a 
displayed image. 

compact disc (CD). (1) A disc, usually 4.75 inches in 
diameter, from which data is read optically by means of a 
laser. (2) A disc with information stored in the form of pits 
along a spiral track. The information is decoded by a 
compact-disc player and interpreted as digital audio data, 
which most computers can process. 

compact disc-extended architecture (CD-EX). A storage 
format that accommodates interleaved storage of audio, video, 
and standard file system data. 


compact disc-read-only memory (CD-ROM). (1) An 

optical storage medium (2) High-capacity, read-only memory 
in the form of an optically read compact disc. 

Complex Mathematics library. A C++ class library that 
provides the facilities to manipulate complex numbers and 
perform standard mathematical operations on them. 

composite. The combination of two or more film, video, or 
electronic images into a single frame or display. 

computer-controlled device. An external video source 
device with frame-stepping capability, usually a videodisc 
player, whose output can be controlled by the multimedia 
subsystem. 

concrete class. A class that implements an abstract data 
type but does not allow polymorphism. 

const. (1) An attribute of a data object that declares that the 
object cannot be changed. (2) An attribute of a function that 
declares that the function will not modify data members of its 
class. 

constructor. A special class member function that has the 
same name as the class and is used to construct and possibly 
initialize objects of its class type. A return type is not 
specified. 

containment function. A function that determines whether a 
collection contains a given element. 

copy constructor. A constructor used to make a copy of an 
object from another object of the same type. 

critical section. Code that must be executed by one thread 
while all other threads in the process are suspended. 

cursor. A reference to an element at a specific position in a 
data structure. 

cursor iteration. The process of repeatedly moving the 
cursor to the next element in a collection until some condition 
is satisfied. 

cursored emphasis. When the selection cursor is on a 
choice, that choice has cursored emphasis. 

C/2. A version of the C language designed for the OS/2 
environment. 
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D 

daemon. A program that runs unattended to perform a 
service for other programs. 

data abstraction. A data type with a private representation 
and a public set of operations. The C++ language uses the 
concept of classes to implement data abstraction. 

DBCS (Double-Byte Character Set). See double-byte 
character set. 

deck. A line of child windows in a set canvas that is 
direction-independent. A horizontal deck is equivalent to a 
row and a vertical deck is equivalent to a column. 

declaration. Introduces a name to a program and specifies 
how the name is to be interpreted. 

declare. To specify the interpetation that C++ gives to each 
identifier. 

default argument. An argument that is declared with a 
default value in a function prototype or declaration. If a call 
to the function omits this argument, the default value is used. 
Arguments with default values must be the trailing arguments 
in a function prototype argument list. 

default class. A class with preprogrammed definitions that 
can be used for simple implementations. 

default constructor. A constructor that takes no arguments, 
or a constructor for which all the arguments have default 
values. 

default implementation. One of several possible 
implementation variants offered as the default for a specific 
abstract data type. 

default operation class. A class with preprogrammed 
definitions for all required element and key operations for a 
particular implementation. 

degree. The number of children of a node. 

delete. (1) A C++ keyword that identifies a free-storage 
deallocation operator. (2) A C++ operator used to destroy 
objects created by operator new. 

deque. A queue that can have elements added and removed 
at both ends. A double-ended queue. 

dequeue. An operation that removes the first element of a 
queue. 


derivation. (1) The creation of a new or derived class from 
an existing base class. (2) The relationship between a class 
and the classes above or below it in a class hierarchy. 

derived class. A class that inherits from a base class. You 
can add new data members and member functions to the 
derived class. You can manipulate a derived class object as 
if it were a base class object. The derived class can override 
virtual functions of the base class. 

Synonym for child class and subclass. 

destructor. A special member function that has the same 
name as its class, preceded by a tilde (~), and that “cleans up” 
after an object of that class, for example, by freeing storage 
that was allocated when the object was created. A destructor 
has no arguments, and no return type is specified. 

difference. Given two sets A and B, the difference (A-B) is 
the set of all elements contained in A but not in B. 

digital audio. Audio data that has been converted to digital 
form. 

digital video. Material that can be seen and that has been 
converted to digital form. 

digital video device. A full-motion video device that can 
record or play files (or both) containing digitally stored video. 

diluted array. An array in which elements are deleted by 
being flagged as deleted, rather than by actually removing 
them from the array and shifting later elements to the left. 

diluted sequence. A sequence implemented using a diluted 
array. 

direct manipulation. A user interface technique whereby 
the user initiates application functions by manipulating the 
objects, represented by icons, on the Presentation Manager 
(PM) or Workplace Shell desktop. The user typically 
initiates an action by: 

1. Selecting an icon 

2. Pressing and holding down a mouse button while 
“dragging” the icon over another object’s icon on the 
desktop 

3. Releasing the mouse button to “drop” the icon over the 
target object. 

Thus, this technique is also known as “drag and drop” 
manipulation. 

double-byte character set (DBCS). A set of characters in 
which each character is represented by 2 bytes. Languages 
such as Japanese, Chinese, and Korean, which contain more 
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symbols than can be represented by 256 code points, require 
double-byte character sets. 

Because each character requires 2 bytes, you need hardware 
and supporting software that are DBCS-enabled to enter, 
display, and print DBCS characters. 

doubleword. A contiguous sequence of bits or characters 
that comprises two computer words and can be addressed as a 
unit. For the C Set-I-H- for AIX compiler, a doubleword is 32 
bits (4 bytes). 

drag after. A target enter event that occurs in a container 
where its orderedTargetEmphasis or mixedTargetEmphasis 
attribute is set and the current view is name, text, or details. 

drag item. A “proxy” for the object being manipulated. 

drag over. A target enter event that occurs in a container 
where its orderedTargetEmphasis attribute is not set and the 
current view is icon or tree view. 

drop offset. The location where the next container object 
that is dropped will be positioned (if the target operation’s 
drop style is not IDM::dropPosition). The position is based 
upon the last object that was dropped as an offset of that 
object relative to the drop style. 

E 

EBCDIC (extended binary-coded decimal interchange 
code). A coded character set of 256 8-bit characters. 

element. The component of an array, subrange, enumeration, 
or set. 

element equality. A relation that determines whether two 
elements are equal. 

element function. A function, called by a member function, 
that accesses the elements of a class. 

encapsulation. The hiding of the internal representation of 
objects and implementation details from the client program. 

enqueue. An operation that adds an element as the last 
element to a queue. 

enumeration constant. An identifier that is defined in an 
enumeration and that has an associated constant integer value. 
You can use an enumeration constant anywhere an integer 
constant is allowed. 


enumeration data type. A type that represents integers and 
a set of enumeration constants. Each enumeration constant 
has an associated integer value. 

equality collection. (1) An abstract class with the property 
of element equality. (2) In general, any collection that has 
element equality. 

equality key collection. An abstract class with the 
properties of element equality and key equality. 

equality key sorted collection. An abstract class with the 
properties of element equality, key equality, and sorted 
elements. 

equality sequence. A sequentially ordered flat collection 
with element equality. 

equality sorted collection. An abstract class with the 
properties of element equality and sorted elements. 

exception. (1) A user or system error detected by the 
system and passed to an OS/2 or user exception handler. 

(2) For C++, any user, logic, or system error detected by a 
function that does not itself deal with the error but passes the 
error on to a handling routine (also called “throwing the 
exception”). 

exception handler. (1) A function that is invoked when an 
exception is detected, and that either corrects the problem and 
returns execution to the program, or terminates the program. 
(2) In C++, a catch block that catches a C++ exception when 
it is thrown from a function in a try block. 

exception handling. A type of error handling that allows 
control and information to be passed to an exception handler 
when an exception occurs. Under the OS/2 operating system, 
exceptions are generated by the system and handled by user 
code. In C++, try, catch, and throw expressions are the 
constructs used to implement C++ exception handling. 

external data definition. A definition appearing outside a 
function. The defined object is accessible to all functions 
that follow the definition and are located within the same 
source file as the definition. 

eyecatcher. A recognizable sequence of bytes that 
determines which parameters were passed in which registers. 
This sequence is used for functions that have not been 
prototyped or have a variable number of parameters. 
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file descriptor. A small positive integer that the system uses 
instead of the file name to identify an open file. 

file scope. A name declared outside all blocks and classes 
has file scope and can be used after the point of declaration 
in a source file. 

filter. A command whose operation consists of reading data 
from standard input or a list of input files and writing data to 
standard output. Typically, its function is to perform some 
transformation on the data stream. 

first element. The element visited first in an iteration over a 
collection. Each collection has its own definition for first 
element. For example, the first element of a sorted set is the 
element with the smallest value. 

flat collection. A collection that has no hierarchical 
structure. 

font. A particular size and style of typeface that contains 
definitions of character sets, marker sets, and pattern sets. 

frame. (1) A complete television picture that is composed 
of two scanned fields, one of the even lines and one of the 
odd lines. In the NTSC system, a frame has 525 horizontal 
lines and is scanned in 1/3Oth of a second. (2) A border 
around a window. 

frame extension. A control you can add if it is not available 
in the basic Presentation Manager frame windows. 

frame number. (1) The number used to identify a frame. 

(2) The location of a frame on a videodisc or in a video file. 
On videodisc, frames are numbered sequentially from 1 to 
54,000 on each side and can be accessed individually; on 
videotape, the numbers are assigned by way of the SMPTE 
time code. 

frame rate. The speed at which the frames are scanned. 

For a videodisc player, the speed at which frames are scanned 
is 30 frames per second for NTSC video. For most videotape 
devices, the speed is 24 frames per second. 

friend class. A class in which all the member functions are 
granted access to the private and protected members of 
another class. It is named in the declaration of the other 
class with the prefix friend. 

friend function. A function that is granted access to the 
private and protected parts of a class. It is named in the 
declaration of the class with the prefix friend. 


full-motion video. (1) Video playback at 30 frames per 
second on NTSC signals. (2) A digital video compression 
technique that operates in real time. 

G 

gain. The ability to change the audibility of the sound, such 
as during a fade in or fade out of music. 

graphic attributes. Attributes that apply to graphic 
primitives. Examples are color, line type, and shading-pattern 
definition. 

graphic primitive. A single item of drawn graphics, such as 
a line, arc, or graphics text string. 

graphical user interface (GUI). Type of computer interface 
consisting of a visual metaphor of a real-world scene, often 
of a desktop. 

graphics. A picture defined in terms of graphic primitives 
and graphic attributes. 

GUI. Graphical user interface. 

H 

halftone. The reproduction of continuous-tone artwork, such 
as a photograph, by converting the image into dots of various 
sizes. 

hash function. A function that determines which category, 
or bucket, to put an element in. A hash function is needed 
when implementing a hash table. 

hash table. A data structure that divides all elements into 
(preferably) equal-sized categories, or buckets, to allow quick 
access to the elements. The hash function determines which 
bucket an element belongs in. 

header file. A file that can contain system-defined control 
information or user data and generally consists of 
declarations. 

heap. An unordered flat collection that allows duplicate 
elements. 

height of a tree. The length of the longest path from the 
root to a leaf. 

hit testing. The means of identifying which graphic object 
the mouse is pointing to. 
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I 

implementation class. A class that implements a concrete 
class. Implementation classes are never used directly. 

incomplete class declaration. A class declaration that does 
not define any members of a class. Typically, you use an 
incomplete class declaration as a forward declaration. 

indirection. A mechanism for connecting objects by storing, 
in one object, a reference to another object. 

inheritance. (1) A mechanism by which a derived class can 
use the attributes, relationships, and member functions 
defined in more abstract classes related to it (its base classes). 
See also multiple inheritance. (2) An object-oriented 
programming technique that allows you to use existing 
classes as bases for creating other classes. 

initializer. An expression used to initialize objects. 

inlined function. A function call that the compiler replaces 
with the actual code for the function. You can direct the 
compiler to inline a function with the inline keyword. 

input stream. A stream used to read input. 

instance number. A number that the operating system uses 
to keep track of all of the instances of the same type of 
device. For example, the amplifier-mixer device name is 
AMPMIX plus a 2-digit instance number. If a program 
creates two amplifier-mixer objects, the device names could 
be AMPMIX01 and AMPMIX02. 

integral object. A character object, an object having an 
enumeration type, an object having variations of the type int, 
or an object that is a bit field. 

interactive graphics. Graphics that a user at a terminal can 
move or manipulate. 

interactive video. The process of combining video and 
computer technology so that the user’s actions, choices, and 
decisions affect the way in which the program unfolds. 

interrupt. A temporary suspension of a process caused by 
an external event, performed in such a way that the process 
can be resumed. 

intersection. Given collections A and B, the set of elements 
that is contained in both A and B. 

intrinsic function. A function supplied by a program as 
opposed to a function supplied by the compiler. 


inverted colors. Opposite colors in the light spectrum. 

iteration. The process of repeatedly applying a function to a 
series of elements in a collection until some condition is 
satisfied. 

iteration order. The order in which elements are accessed 
when iterating over a collection. In ordered collections, the 
element at position 1 will be accessed first, then the element 
at position 2, and so on. In sorted collections, the elements 
are accessed according to the ordering relation provided for 
the element type. In collections that are not ordered the 
elements are accessed in an arbitrary order. Each element is 
accessed exactly once. 

iterator class. A class that provides iteration functions. 

I/O Stream Library. A class library that provides the 
facilities to deal with many varieties of input and output. 

K 

key access. A property that allows elements to be accessed 
by matching keys. 

key bag. An unordered flat collection that uses keys and can 
contain duplicate elements. 

key collection. (1) An abstract class that has the property of 
key access. (2) In general, any collection that uses keys. 

key equality. A relation that determines whether two keys 
are equal. 

key() function. When used on a flat collection, a function 
that returns a reference to the key of an element. 

key-type function. Any of several functions of an element 
type, that are used by the Collection Class Library member 
functions to manipulate the keys of a class. 

key set. An unordered flat collection that uses keys and 
does not allow duplicate elements. 

key sorted bag. A sorted flat collection that uses keys and 
allows duplicate elements. 

key sorted collection. An abstract class with the properties 
of key equality and sorted elements. 

key sorted set. A sorted flat collection that uses keys and 
does not allow duplicate elements. 
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keyword. (1) A predefined word reserved for the C or C++ 
language that you cannot use as an identifier. (2) A symbol 
that identifies a parameter. 

L 

last element. The element accessed last in an iteration over 
a collection. Each collection has its own definition for last 
element. For example, the last element of a sorted set is the 
element with the largest value. 

latched. The state of a button. A button in its latched state 
is held in its pressed position until the user clicks on it to 
release (unlatch) it. 

leaves. In a tree, nodes without children. Synonymous with 
terminals. 

library. (1) A collection of functions, function calls, 
subroutines, or other data. (2) A set of object modules that 
can be specified in a link command. 

linkage editor. Synonym for linker. 

linked implementation. An implementation in which each 
element contains a reference to the next element in the 
collection. Pointer chains are used to access elements in 
linked implementations. Linked implementations are also 
called linked list implementations. 

linked sequence. A sequence that uses a linked 
implementation. 

linker. A program that resolves cross-references between 
separately compiled object modules and then assigns final 
addresses to create a single executable program. 

locale. The definition of the subset of a user's environment 
that depends on language and cultural conventions. 

lvalue. An expression that represents an object that can be 
both examined and altered. 

M 

manipulator. A value that can be inserted into streams or 
extracted from streams to affect or query the behavior of the 
stream. 

mask. A pattern of bits or characters that controls the 
keeping, deleting, or testing of portions of another pattern of 
bits or characters. 


MBCS (Multibyte Character Set). See multibyte character 
set 

member. Data, functions, or types contained in classes, 
structures, or unions. 

member function. An operator or function that is declared 
as a member of a class. A member function has access to the 
private and protected data members and member functions of 
objects of its class. 

message. A request from one object that the receiving object 
implement a method. Because data is encapsulated and not 
directly accessible, a message is the only way to send data 
from one object to another. Each message specifies the name 
of the receiving object, the method to be implemented, and 
any parameters the method needs for implementation. 

method. Synonym for member function. 

MIDI. Musical Instrument Digital Interface. A standard 
used in the music industry for interfacing digital musical 
instruments. 

mix. (1) An attribute that determines how the foreground of 
a graphic primitive is combined with the existing color of 
graphics output. Also known as foreground mix. Contrast 
with background mix. (2) The combination of audio or 
video sources during postproduction. 

mixer. A device used to simultaneously combine and blend 
several inputs into one or two outputs. 

mode. A collection of attributes that specifies a file's type 
and its access permissions. 

motion video. Video that displays real motion. 

mount. (1) To place a data medium in a position to operate. 
(2) To make recording media accessible. 

Moving Pictures Experts Group (MPEG). (1) A group 
that is working to establish a standard for compressing and 
storing motion video and animation in digital form. (2) The 
compression standard of video and audio data that is stored 
on mass media. 

MPEG. Moving Pictures Experts Group. 

multibyte character set (MBCS). A character set whose 
characters consist of more than 1 byte. Used in languages 
such as Japanese, Chinese, and Korean, where the 256 
possible values of a single-byte character set are not sufficient 
to represent all possible characters. 
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multimedia. Computer-controlled presentations combining 
any of the following: text, graphics, animation, full-motion 
images, still video images, and sound. 

multiple inheritance. (1) An object-oriented programming 
technique implemented in C++ through derivation, in which 
the derived class inherits members from more than one base 
class. (2) The structuring of inheritance relationships among 
classes so a derived class can use the attributes, relationships, 
and functions used by more than one base class. 

See also inheritance and class lattice. 

multitasking. A mode of operation that allows concurrent 
performance or interleaved execution of more than one task 
or program. 

multithread. Pertaining to concurrent operation of more 
than one path of execution within a computer. 

N 

n-ary tree. A tree that has an upper limit, n, imposed on the 
number of children allowed for a node. 

National Television Standard Committee (NTSC). (1) A 

committee that sets the standard for color television 
broadcasting and video in the United States (currently in use 
also in Japan). (2) The standard set by the NTSC committee 
(the NTSC standard). 

native. The rendering mechanism and format (RMF) that 
best represents the object and is the best one for rendering. 

For example, a native of Cincinnati understands the streets in 
the area better than someone who has just moved there. 
Therefore, a Cincinnati native can get from point A to point 
B quicker than a newcomer. Likewise, a native RMF can get 
the data transferred from point A to point B more efficiently 
than the additional RMFs. We can use additional RMFs 
when we cannot use the native, or optimal, approach. 

nested class. A class defined within the scope of another 
class. 

new. (1) A C++ keyword identifying a free storage 
allocation operator. (2) A C++ operator used to create class 
objects. 

new-line character. A control character that causes the print 
or display position to move to the first position on the next 
line. This control character is represented by \n in the C 
language. 


node. In a tree structure, a point at which subordinate items 
of data originate. 

NTSC. National Television Standard Committee. 

NTSC format. The specifications for color television as 
defined by the NTSC, which include: (a) 525 scan lines, (b) 
broadcast bandwidth of 4 megaHertz, (c) line frequency of 
15.75 kiloHertz, (d) frame frequency of 30 frames per 
second, and (e) color subcarrier frequency of 3.58 megaHertz. 

null character (\0). The ASCII or EBCDIC character with 
the hex value 00 (all bits turned off). 

O 

object. (1) A collection of data and member functions that 
operate on that data, which together represent a logical entity 
in the system. In object-oriented programming, objects are 
grouped into classes that share common data definitions and 
functions. Each object of the class is said to be an instance 
of the class. (2) Each object has the same properties, 
attributes, and member functions as other objects of the same 
class, though it has unique values has unique values assigned 
to assigned to its attributes. 

object-oriented programming. A programming approach 
based on the concepts of data abstraction and inheritance. 
Unlike procedural programming techniques, object-oriented 
programming concentrates on what data objects comprise the 
problem and how they are manipulated, not on how 
something is accomplished. 

operation class. A class that defines all required element 
and key operations required by a specific collection 
implementation. 

operator function. An overloaded operator that is either a 
member of a class or that takes at least one argument that is a 
class type or a reference to a class type. See overloading. 

optical reflective disc. An optical videodisc that is read by 
means of the reflection of a laser beam from the shiny 
surface on the disc. 

ordered collection. (1) An abstract class that has the 
property of ordered elements. (2) In general, any collection 
that has its elements arranged so that there is always a first 
element, last element, next element, and previous element. 

ordering relation. A property that determines how the 
elements are sorted. Ascending order is an example of an 
ordering relation. 
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overflow. A condition that occurs when a portion of the 
result of an operation exceeds the capacity of the intended 
unit of storage. 

overloading. An object-oriented programming technique 
where one or more function declarations are specified for a 
single name in the same scope. 

owner window. A window similar to a parent window, but 
it does not affect the behavior or appearance of the window. 
The owner coordinates the activity of a window. 

P 

pad. To fill unused positions in a field with data, usually 
0’s, l’s, or blanks. 

parameter declaration. A description of a value that a 
function receives. A parameter declaration determines the 
storage class and the data type of the value. 

parent node. A node to which one or more other nodes are 
subordinate. 

parent window. A window that provides the child window 
information on how and where to draw it. The parent 
window also defines the relationship that the child window 
has with other windows in the system. 

pause. To temporarily halt the medium. The halted visual 
should remain displayed but no audio should be played. 

pel. The smallest area of a display screen capable of being 
addressed and switched between visible and invisible states. 
Synonym for pixel and picture element. 

picture element. Synonym for pel. 

pitch. The ability to change the key or keynote of the 
sound. For example, in music, the different pitches of 
people’s voices are soprano, alto, tenor, baritone, and bass, 
arranged from the highest to lowest pitch. 

pixel. Picture element. Synonym for pel. 

pointer. A variable that holds the address of a data object or 
function. 

pointer class. A class that implements pointers. 

pointer to member. An operator used to access the address 
of nonstatic members of a class. 


polymorphic function. A function that can be applied to 
objects of more than one data type. C++ implements 
polymorphic functions in two ways: 

1. Overloaded functions (calls are resolved at compile time) 

2. Virtual functions (calls are resolved at run time) 

polymorphism. The technique of taking an abstract view of 
an object or function and using any concrete objects or 
arguments that are derived from this abstract view. 

positioning property. The property of an element that is 
used to position the element in a collection. For example, the 
value of the key may be used as the positioning property. 

precondition. A condition that a function requires to be true 
when it is called. 

predicate function. A function that returns an IBoolean 
value of true ox false. (IBoolean is an integer-represented 
Boolean type.) 

preparation. Any activity that the source performs before 
rendering the data. For example, the drag item may require 
that the source create a secondary thread for the source 
rendering to take place in. The system remains responsive to 
users so that they can do other tasks. 

preprocessor. A phase of the compiler that examines the 
source program for preprocessor statements, which are then 
executed, resulting in the alteration of the source program. 

preroll. To prepare a device to begin a playback or 
recording function with minimal delay. 

primitive. See graphic primitive. 

primitive attribute. A specifiable characteristic of a graphic 
primitive. See graphic attributes. 

priority queue. A queue that has a priority assigned to its 
elements. When accessing elements, the element with the 
highest priority is removed first. A priority queue has a 
largest-in, first-out behavior. 

private. Pertaining to a class member that is accessible only 
to member functions and friends of that class. 

process. A program running under OS/2, along with the 
resources associated with it (memory, threads, file system 
resources, and so on). 

profiling. The process of generating a statistical analysis of 
a program that shows processor time and the percentage of 
program execution time used by each procedure in the 
program. 
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program. (1) One or more files containing a set of 
instructions conforming to a particular programming language 
syntax. (2) A self-contained, executable module. Multiple 
copies of the same program can be run in different processes. 

property function. A function that is used to determine 
whether the element it is applied to has a given property or 
characteristic. A property function can be used, for example, 
to remove all elements with a given property. 

protected. Pertaining to a class member that is only 
accessible to member functions and friends of that class, or to 
member functions and friends of classes derived from that 
class. 

prototype. A function declaration or definition that includes 
both the return type of the function and the types of its 
arguments. 

public. Pertaining to a class member that is accessible to all 
functions. 

pure virtual function. A virtual function that has a function 
initializer of the form = 0;. 

Q 

queue. A sequence with restricted access in which elements 
can only be added at the back end (or bottom) and removed 
from the front end (or top). A queue is characterized by 
first-in, first-out behavior and chronological order. 

R 

reference class. A class that links a concrete class to an 
abstract class. Reference classes make polymorphism 
possible with the Collection Classes. 

relation. An unordered flat collection class that uses keys, 
allows for duplicate elements, and has element equality. 

Tenderer. An object that renders data using a particular 
mechanism, such as using files or shared memory. It 
contains definitions of supported rendering mechanisms and 
formats and types. Renderers are maintained positionally 
(1-based). 

rendering. The transfer or re-creation of the dragged object 
from the source window to the target window. 

rendering format. Identifies the actual format of the data 
being rendered in a direct manipulation operation. 


rendering mechanism. Identifies the actual format of the 
data being rendered in a direct manipulation operation. 

resource file. A file that contains data used by an 
application, such as text strings and icons. 

returned element. An element returned by a function as the 
return value. 

RGB. Red, green, blue. A method of processing color 
images according to their red, green, and blue color content. 

RMFs. Rendering mechanisms and formats. 

root. A node that has no parent. All other nodes of a tree 
are descendants of the root. 

S 

samples-per-second. The number of times per second that 
the audio card records data from the audio input. For 
example, 44 kiloHertz is CD quality; 22 kiloHertz is FM 
music quality; and 11 kiloHertz is voice quality. 

SBCS (Single-Byte Character Set). See single-byte 
character set 

scan. To search backward and forward at high speed on a 
CD audio device. Scanning is analogous to fast forwarding. 

scope. That part of a source program in which an object is 
defined and recognized. 

scope operator (::). An operator that defines the scope for 
the argument on the right. If the left argument is blank, the 
scope is global; if the left argument is a class name, the 
scope is within that class. Also called a scope resolution 
operator. 

scroll increment. The number by which the current value of 
the circular slider is incremented or decremented when a user 
presses one of the circular slider control buttons. 

sequence. A sequentially ordered flat collection. 

sequential collection. An abstract class with the property of 
sequentially ordered elements. 

siblings. All the children of a node are said to be siblings of 
one another. 

single-byte character set (SBCS). A set of characters in 
which each character is represented by a 1-byte code. 
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SMPTE time code. A frame-numbering system developed 
by SMPTE that assigns a number to each frame of video. 

The 8-digit code is in the form HH:MM:SS:FF (hours, 
minutes, seconds, frame number). The numbers track elapsed 
hours, minutes, seconds, and frames from any chosen point. 

sorted bag. A sorted flat collection that allows duplicate 
elements. 

sorted collection. (1) An abstract class with the property of 
sorted elements. (2) In general, any collection with sorted 
elements. 

sorted map. A sorted flat collection with key and element 
equality. 

sorted relation. A sorted flat collection that uses keys, has 
element equality, and allows duplicate elements. 

sorted set. A sorted flat collection with element equality. 

sound track. Synonymous with audio track. 

sprite. A small graphic that can be moved independently 
around the screen, producing animated effects. 

stack. A data structure in which new elements are added to 
and removed from the top of the structure. A stack is 
characterized by Last-In-First-Out (LIFO) behavior. 

standard error. An output stream usually intended to be 
used for diagnostic messages. 

standard input. An input stream usually intended to be 
used for primary data input. Standard input comes from the 
keyboard unless redirection or piping is used, in which case 
standard input can be from a file or the output from another 
command. 

standard output. An output stream usually intended to be 
used for primary data output. When programs are run 
interactively, standard output usually goes to the display 
unless redirection or piping is used, in which case standard 
output can go to a file or to another command. 

step backward. In multimedia applications, to move the 
medium backward one frame or segment at a time. 

step forward. In multimedia applications, to move the 
medium forward one frame or segment at a time. 

step frame. A function of devices such as digital video and 
videodisc players that enables a user to move frame-by-frame 
in either direction. 


stream. (1) A continuous stream of data elements being 
transmitted, or intended for transmission, in character or 
binary-digit form, using a defined format. (2) A file access 
object that allows access to an ordered sequence of 
characters, as described by the ISO C standard. A stream 
provides the additional services of user-selectable buffering 
and formatted input and output. 

stream buffer. A stream buffer is a buffer between the 
ultimate consumer, ultimate producer, and the I/O Stream 
Library functions that format data. It is implemented in the 
I/O Stream Library by the streambuf class and the classes 
derived from streambuf. 

string. A contiguous sequence of characters. 

structure. A construct that contains an ordered group of 
data objects. Unlike an array, the data objects within a 
structure can have varied data types. 

subclass. See derived class. 

subscript. One or more expressions, each enclosed in 
brackets, that follow an array name. A subscript refers to an 
element in an array. 

subtree. A tree structure created by arbitrarily denoting a 
node to be the root node in a tree. A subtree is always part 
of a whole tree. 

superclass. See base class and abstract class. 

superset. Given two sets A and B, A is a superset of B if 
and only if all elements of B are also elements of A. That is, 
A is a superset of B if B is a subset of A. 

T 

tabular implementation. An implementation that stores the 
location of elements in tables. Elements in a tabular 
implementation are accessed by using indices to arrays. 

tabular sequence. A sequence that uses a tabular 
implementation. 

template. A family of classes or functions where the code 
remains invariant but operates with variable types. 

terminals. Synonym for leaves. 

this. A C++ keyword that identifies a special type of pointer 
in a member function, one that references the class object 
with which the member function was invoked. 
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this collection. The collection to which a function is 
applied. 

thread. A unit of execution within a process. 

throw expression. An argument to the C++ exception being 
thrown. 

time code. See SMPTE time code. 

tool bar. The area under the title bar that displays the tools 
available. 

transparency. Refers to when a selected color on a graphics 
screen is made transparent to allow the video behind it to 
become visible. 

transparent color. (1) A clear color used to indicate the 
part of the bitmap that is not drawn for the bitmap. The area 
under the bitmap is not overpainted for areas of the bitmap 
that are set to the transparent color. (2) Video information is 
considered as being present on the video plane that is 
maintained behind the graphics plane. When an area on the 
graphics plane is painted with a transparent color, the video 
information in the video plane is made visible. 

trap. An unprogrammed conditional jump to a specified 
address that is automatically activated by hardware. A 
recording is made of the location from which the jump 
occurred. 

treble. (1) The upper half of the whole vocal or 
instrumental tonal range. (2) The higher portion of the audio 
frequency range in sound recording. 

tree. A hierarchical collection of nodes that can have an 
arbitrary number of references to other nodes. A unique path 
connects every two nodes. 

true and additional. The most accurate or most descriptive 
(primary) type of an object (true) and the other or secondary 
types (additional). For example, if the object is a text file, its 
true type is text; if the file was a C source code file, its true 
type is C code. 

try block. A block in which a known C++ exception is 
passed to a handler. 

typed implementation class. A class that implements a 
concrete class and provides an interface that is specific to a 
given element type. This interface allows the compiler to 
verify that, for example, integers cannot be added to a set of 
strings. 


typeless implementation class. A class that implements a 
concrete class and provides an interface that is not specific to 
a given element type. 

U 

ultimate consumer. The target of data in an I/O operation. 
An ultimate consumer can be a file, a device, or an array of 
bytes in memory. 

ultimate producer. The source of data in an I/O operation. 
An ultimate producer can be a file, a device, or an array of 
byes in memory. 

unbounded collection. A collection that has no upper limit 
on the number of elements it can contain. 

undefined cursor. A cursor that may or may not be valid, 
and that may or may not refer to a different element of the 
collection from the element it referred to before the function 
call that resulted in its becoming undefined. An undefined 
cursor may refer to no element of the collection, and still be 
a valid cursor. 

underflow. (1) A condition that occurs when the result of 
an operation is less than the smallest possible nonzero 
number. (2) Synonym for arithmetic underflow, monadic 
operation. 

union. (1) Structures that can contain different types of 
objects at different times. Only one of the member objects 
can be stored in a union at any time. (2) Given the sets A 
and B, all elements of A, B, or both A and B. 

unique collection. A collection in which the value of an 
element only occurs once; that is, there are no duplicate 
elements. 

unload. To eject the medium from the device. 

unordered collection. A collection that has no order to its 
elements. 

V 

VCR. Videocassette recorder. 

VGA. Video graphics adapater. 

video. Pertaining to the portion of recorded information that 
can be seen. 
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video attributes. The standard video attributes are: 
brightness, contrast, freeze, hue, saturation, and sharpness. 

video graphics adapter (VGA). A graphics controller for 
color displays. The pel resolution of the video graphics 
adapter is 4:4. 

videocassette recorder (VCR). A device for recording or 
playing back videocassettes. 

videodisc. A disc on which programs have been recorded 
for playback on a computer or a television set; a recording on 
a videodisc. The most common format in the United States 
and Japan is an NTSC signal recorded on the optical 
reflective format. 

videodisc player. A device that provides video playback for 
prerecorded videodiscs. 

virtual function. A function of a class that is declared with 
the keyword virtual. The implementation that is executed 
when you make a call to a virtual function depends on the 
type of the object for which it is called. This is determined 
at run time. 

volatile. An attribute of a data object that indicates the 
object is changeable beyond the control or detection of the 
compiler. Any expression referring to a volatile object is 
evaluated immediately, for example, assignments. 

volume. The intensity of sound. A volume of 0 is minimum 
volume. A volume of 100 is maximum volume. 


W 

white space. Space characters, tab characters, form feed 
characters, and new-line characters. 

wide character. A character whose range of values can 
represent distinct codes for all members of the largest 
extended character set specified among the supporting locales. 

Numerics 

24-bit color. A digital standard that uses 24 bits of 
information to describe each color pixel, providing up to 16.7 
million colors in one image (the highest digital standard 
currently available). 

8-bit color. A digital standard that uses 8 bits of 
information to describe each color pixel, providing up to 256 
colors in one image (the standard for VGA displays). 

Special Characters 

(::) (double colon). Scope operator. An operator that 
defines the scope for the argument on the right. If the left 
argument is blank, the scope is global; if the left argument is 
a class name, the scope is within that class. Also called a 
scope resolution operator. 
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IDMSourceDiscardEvent 456 
'IDMSourceEndEvent 

IDMSourceEndEvent 458 
'IDMSourceFlandler 

IDMSourceFlandler 461 
'IDMSourceOperation 

IDMSourceOperation 468 
'IDMSourcePrepareEvent 

IDMSourcePrepareEvent 473 
'IDMSourcePrintEvent 

IDMSourcePrintEvent 477 
'IDMSourceRenderer 

IDMSourceRenderer 480 
'IDMSourceRenderEvent 

IDMSourceRenderEvent 485 
'IDMTargetDropEvent 

IDMTargetDropEvent 490 
'IDMTargetEndEvent 

IDMTargetEndEvent 494 
'IDMTargetEnterEvent 

IDMTargetEnterEvent 498 
'IDMTargetEvent 

IDMTargetEvent 501 
'IDMTargetHandler 

IDMTargetHandler 505 
'IDMTargetHelpEvent 

IDMTargetHelpEvent 510 
'IDMTargetLeaveEvent 

IDMTargetLeaveEvent 513 
'IDMTargetOperation 

IDMTargetOperation 515 
'IDMTargetRenderer 

IDMTargetRenderer 520 
'IDMTB arB uttonltem 

IDMTBarButtonltem 526 
'IDMToolBarltem 

IDMToolBarltem 532 
"IDrawingCanvas 

IDrawingCanvas 537 
'IFileDialog 

IFileDialog 547 
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"IFileDialogEvent 

IFileDialogEvent 563 
"IFileDialogHandler 

IFileDialogFIandler 566 
“IFlyOverFIelpI landler 

IFlyOverHelpFlandler 573 
'IFlyText 

IFlyText 581 
'IFont 

IFont 587 
'IFontDialog 

IFontDialog 608 
'IFontDialogHandler 

IFontDialogFlandler 622 
'IG3PointArc 

IG3PointArc 627 
'IGArc 

IGArc 631 
'IGBitmap 

IGBitmap 639 
'IGChord 

IGChord 651 
'IGEllipse 

IGEllipse 655 
'IGLine 

IGLine 658 
'IGList 

IGList 663 
'IGPie 

IGPie 675 
'IGPolygon 

IGPolygon 680 
'IGPolyline 

IGPolyline 683 
'IGraphic 

IGraphic 691 
'IGraphicB undle 

IGraphicBundle 703 
"IGraphicContext 

IGraphicContext 723 
'IGraphicPushButton 

IGraphicPushButton 747 
'IGRectangle 

IGRectangle 757 
'IGRegion 

IGRegion 761 
'IGString 

IGString 781 
'IlconControl 

IlconControl 786 


'IlnfoArea 

IlnfoArea 795 
~IMM24FramesPerSecondTime 

IMM24FramesPerSecondTime 804 
'IMM25FramesPerSecondTime 

IMM25FramesPerSecondTime 807 
~IMM30FramesPerSecondTime 

IMM30FramesPerSecondTime 810 
'IMMAmpMixer 

IMMAmpMixer 813 
'IMMAudioBuffer 

IMMAudioBuffer 825 
"IMMAudioCD 

IMMAudioCD 834 
'IMMAudioCDContents 

IMMAudioCDContents 847 
'IMMCDXA 

IMMCDXA 856 
'IMMConfigurableAudio 

IMMConfigurableAudio 866 
'IMMCuePointEvent 

IMMCuePointEvent 870 
'IMMDevice 

IMMDevice 884 
'IMMDeviceEvent 

IMMDeviceEvent 905 
'IMMDeviceFlandler 

IMMDeviceFlandler 909 
'IMMDigital Video 

IMMDigitalVideo 915 
'IMMErrorlnfo 

IMMErrorlnfo 935 
'IMMFileMedia 

IMMFileMedia 937 
'IMMHourMinSecFrameTime 

IMMFlourMinSecFrameTime 946 
'IMMHourMinSecTime 

IMMFlourMinSecTime 950 
'IMMMasterAudio 

IMMMasterAudio 954 
'IMMMillisecondTime 

IMMMillisecondTime 959 
'IMMMinSecFrameTime 

IMMMinSecFrameTime 962 
'IMMN otifyEvent 

IMMNotifyEvent 966 
'IMMPassDeviceEvent 

IMMPassDeviceEvent 969 
'IMMPlayableDevice 

IMMPlayableDevice 977 
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'IMMPlayerPanel 

IMMPlayerPanel 986 
'IMMPlayerPanelHandler 

IMMPlayerPanelHandler 991 
'IMMPositionChangeEvent 

IMMPositionChangeEvent 995 
'IMMRecordable 

IMMRecordable 998 
'IMMRemovableMedia 

IMMRemovableMedia 1010 
'IMMRemovableMediaHandler 

IMMRemovableMediaHandler 1017 
'IMMSequencer 

IMMSequencer 1020 
'IMMSpeed 

IMMSpeed 1025 
'IMMTime 

IMMTime 1028 
~IMMT rackMinS ecFrameTime 

IMMTrackMinSecFrameTime 1037 
~IMM W ave Audio 

IMM W ave Audio 1044 
'IMultiCellCanvas 

IMultiCellCanvas 1056 
'INotebook 

INotebook 1073 
~IN otebookDrawItemEvent 

INotebookDrawItemEvent 1113 
~IN otebookN otify Handler 

IN otebookN otify Handler 1116 
'IPageEvent 

IPageEvent 1119 
'IPageHandler 

IPageHandler 1124 
~IPageHelpEvent 

IPageHelpEvent 1128 
'IPageRemoveEvent 

IPageRemoveEvent 1131 
'IPageSelectEvent 

IPageSelectEvent 1134 
'ISetCanvas 

ISetCanvas 1140 
'ISplitCanvas 

ISplitCanvas 1162 
'IStringGenerator 

IStringGenerator 1173 
'IStringGeneratorFn 

IStringGeneratorFn 1176 
~IStringGeneratorMemberFn 

IStringGeneratorMemberFn 1179 


'IStringGeneratorRefMemberFn 

IStringGeneratorRefMemberFn 1182 
'Iterator 

IContainerControl: iterator 228 
“IToolBar 

IToolBar 1186 
“IToolBarButton 

IToolBarButton 1209 
“IToolBarContainer 

IToolBarContainer 1222 
“IToolB arFrame W indo w 

IToolBarFrameWindow 1229 
“ITransformMatrix 

ITransformMatrix 1235 
“I ViewPort 

I ViewPort 1242 
'ObjectCursor 

IContainerControl: :ObjectCursor 230 
'PageSettings 

INotebook: :PageSettings 1105 
'PointSizeCursor 

IFont::PointSizeCursor 603 
'Settings 

IFileDialog:: Settings 556 
IFontDialog:: Settings 617 
'TextCursor 

IContainerControl:: TextCursor 235 
'WindowCursor 

IToolBar: :WindowCursor 1204 

A 

accelerator 

acceptConversation 

IDDETopicServer 353 
accessor functions 
acknowledged 

IDDEClientConversation 307 
IDDETopicServer 353 
acquire 

IMMDevice 889 
addAsFirst 
IGList 662 
IToolBar 1190 
addAsLast 
IGList 662 
IToolBar 1191 
addAsNext 
IGList 662 
IToolBar 1191 
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addAsPrevious 
IGList 662 
IToolBar 1191 
addAtPosition 
IGList 662 
addColumn 

IContainerControl 179 
addCuePoint 

IMMPlayableDevice 972 
addDrive 

IFileDialog:: Settings 558 
addEntryAsFirst 

IMMAudioCDContents 847 
addEntryAsNext 

IMMAudioCDContents 847 
addFileType 

IFileDialog:: Settings 558 
addFirstPage 

INotebook 1074 
addld 

IContainerControl 213 
addltem 

IDMOperation 441 
addLastPage 

INotebook 1075 
addObject 

IContainerControl 167 
addObject After 

IContainerControl 167 
addObjects 

IContainerControl 167 
addObjects After 

IContainerControl 167 
addPageAfter 

INotebook 1075 
addPageBefore 

INotebook 1076 
addPoint 

IGPolyline 684 
addRenderer 

IDMHandler 385 
IDMSourceHandler 461 
IDMTargetHandler 505 
addRMF 

IDMItem 413 
addSourceEmphasis 

ICnrMenuHandler 105 
addToCell 

IMultiCellCanvas 1053 


addType 

IDMItem 410 

Advanced Controls, Dialogs, and their Handlers xx 
overview xx 
aliasName 

IMMDevice 884 
alignBottom 

IContainerColumn 160 
alignCentered 

IContainerColumn 160 
alignLeft 

IContainerColumn 160 
alignment 

ISetCanvas 1142 
alignRight 

IContainerColumn 160 
alignTitleCentered 

IContainerControl 210 
alignTitleLeft 

IContainerControl 210 
alignTitleRight 

IContainerControl 210 
alignTop 

IContainerColumn 161 
align V ertically Centered 
IContainerColumn 161 
allDevices 

IMMDevice 898 
allObjectsDo 

IContainerControl 185 
allocateOperation 

IDMSourceHandler 465 
IDMTargetHandler 508 
allowsDragDelete 

IToolB arB utton 1209 
allowsDragDrop 
IToolBar 1186 
alternate W indo w 

IDMSourcePrepareEvent 473 
IDMSourceRenderEvent 485 
IDMTargetEndEvent 493 
alternate W indo wHandle 

IDMSourcePrepareEvent 473 
IDMSourceRenderEvent 485 
IDMTargetEndEvent 494 
alwaysHorizontalScrollBar 
I ViewPort 1248 
alwaysVerticalScrollBar 
I ViewPort 1248 
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amount 

ICnrScrollEvent 117 
ampMixer 

IMMDevice 898 
IAnimatedButton 8 
IAnimatedButton::Style 17 
animate WhenLatched 
IAnimatedButton 15 
animation 

IMMDevice 898 
animationRate 

IAnimatedButton 9 
any 

IDM 359 
appendRMF 

IDMItem 411 
application 

IDDEActiveServer 287 
IDDEB eginEvent 291 
IDDEClientConversation 300 
IDDEClientEndEvent 312 
IDDETopicServer 349 
application classes 
overview xix 
applications 

applicationSpecificData 

IDDEAcknowledgeEvent 277 
apply Button 

IFileDialog 552 
IFontDialog 612 
apply To 

IContainerControl:: Iterator 228 
areChildrenReversed 
ICanvas 33 

areDetails V iewT itles Visible 
IContainerControl 169 
areHeadphonesEnabled 
IMMMasterAudio 954 
areSpeakersEnabled 

IMMMasterAudio 955 
armRange 

ICircularSlider 38 
arrangelcon V iew 

IContainerControl 175 
aslndex 

IMMAudioCDContents:: Cursor 852 
asMATRIXLF 

ITransformMatrix 1235 
asMMTime 

IMMTime 1028 


asNeededHorizontalScrollBar 
I ViewPort 1248 
asN eeded V erticalScrollB ar 
I ViewPort 1249 
asPointerHandle 
IGBitmap 635 
asString 

IMMHourMinSecFrameTime 946 
IMMHourMinSecTime 951 
IMMMinSecFrameTime 963 
IMMTime 1028 

IMMTrackMinSecFrameTime 1037 
atBottomDelta 

ICnrQueryDeltaEvent 110 
atFirstObject 

ICnrQueryDeltaEvent 110 
atLastObject 

ICnrQueryDeltaEvent 110 
atTopDelta 

ICnrQueryDeltaEvent 110 
attributes 

IContainerControl 208 
IDMItem 404 
audio 

IMMAudioBuffer 826 
audioCD 

IMMDevice 898 
audioTape 

IMMDevice 898 
autoLatch 

ICustomButton 261 
autoPageSize 

INotebook::PageSettings 1107 
autoPosition 

IContainerControl 214 
avgCharWidth 
IFont 589 
avgLowercase 
IFont 589 
avgUppercase 
IFont 590 

B 

backgroundColor 
ICanvas 28 
ICustomButton 254 
IGraphicBundle 700 
IGraphicContext 732 
INotebook 1068 
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backgroundMixMode 
IGraphicBundle 699 
IGraphicContext 732 
backPagesB ottomLeft 
INotebook 1092 
backPagesBottomRight 
INotebook 1092 
backPagesTopLeft 
INotebook 1092 
backPagesTopRight 
INotebook 1092 
backwardDiagl 

IGraphicBundle 713 
backwardDiag2 

IGraphicBundle 714 
balance 

IMMAmpMixer 813 
baseRecord 

IContainerObject 250 
baseRecordSize 

IContainerControl 208 
Basic Control Classes xx 
overview xx 
bass 

IMMAmpMixer 814 
begin 

IDDEClientConversation 301 
IDMSourceOperation 469 
beginConversation 

IDDETopicServer 348 
beginEdit 

ICnrEditHandler 80 
beginHotLink 

IDDEClientConversation 302 
IDDETopicServer 354 
beginUsingFont 
IFont 588 
binary 

IDM 359 
binaryData 
IDM 359 
binding 

INotebook 1068 
bitmap 

IAnimatedButton 10 
IBitmapControl 18 
IDM 359 
IDMImage 390 
IGraphicPushButton 747 
IToolBarButton 1207 


bitmapAndTextVisible 
IToolBarButton 1216 
IBitmapControl 18 
IBitmapControl: :Style 26 
bitmapCount 

IAnimatedButton 11 
bitmapFormat 
IDDE 272 
bitmapOnly 

IFontDialog 613 
bitmapSize 

IToolB arB utton 1207 
bitmap Visible 

IToolBarButton 1217 
bitsPerS ample 

IMMAudioBuffer 822 
IMMConfigurableAudio 860 
bitwise operators 
black 

IGBitmap 645 
blockAlignment 

IMMAudioBuffer 822 
IMMConfigurableAudio 861 
bmp 

IDMImage 393 
books, related 

BookManager 1363 
OS/2 1362 
portability 1362 
VisualAge C++ 1362 

border 

ISetCanvas 1148 
bottomAlign 

ISetCanvas 1148 
bottomGraphicUnderPoint 
IGList 664 
boundingRect 
IGraphic 688 
boundingRectAt 
IGList 664 
buffer 

IDDEEvent 327 
buttonB itmap AndT ext V isible 
IToolB ar 1197 
buttonB itmap Visible 
IToolB ar 1197 
buttonPressedld 
IFileDialog 548 
IFontDialog 609 
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buttons 

ICircularSlider 45 
buttonState 

ICustomButtonDrawEvent 265 
buttonTextVisible 
IToolBar 1197 
button View 

IToolBar 1190 
bytesPerSecond 

IMMAudioBuffer 822 
IMMConfigurableAudio 861 

c 

C Set ++ for AIX 
C++ 

calcMinimumSize 

IAnimatedButton 14 
IBitmapControl 23 
ICanvas 33 
ICircularSlider 44 
IContainerControl 208 
ICustomButton 260 
IDrawingCanvas 539 
IGraphicPushButton 751 
IlconControl 789 
IlnfoArea 800 
INotebook 1090 
IToolBar 1196 
IToolBarButton 1216 
IViewPort 1246 
canBeCopied 

IDMItem 402 
canBeLinked 

IDMItem 402 
canBeMoved 

IDMItem 402 
cancel 

IFileDialog 551 
IFontDialog 612 
canRedo 

IMMRecordable 999 
canRender 

IDMSourceRenderer 480 
IDMTargetRenderer 520 
canRetry 

IDMSourceRenderEvent 486 
canUndo 

IMMRecordable 999 


ICanvas 27 
canvas classes 
ICanvas::Style 36 
cdxa 

IMMDevice 898 
centerAlign 

ISetCanvas 1148 
centerPoint 
IGLine 659 
centerVerticalAlign 
ISetCanvas 1148 
changed 

ICnrEmphasisEvent 84 
channels 

IMMAudioBuffer 822 
IMMConfigurableAudio 862 
charWidth 
IFont 590 
check box control 
circular Arm 

ICircularSlider 45 
ICircularSlider 37 
ICircularSlider: :Style 48 
ICircularSliderNotifyHandler 49 
classDefaultAttribute 

IContainerControl 210 
classDefaultDataStyle 

IContainerColumn 158 
classDefaultHeadingStyle 
IContainerColumn 160 
classDefaultStyle 

IAnimatedButton 15 
IBitmapControl 24 
ICanvas 35 
ICircularSlider 45 
IContainerControl 214 
ICustomButton 261 
IDMImage 393 
IDrawingCanvas 540 
IFileDialog 552 
IFontDialog 613 
IGraphicPushButton 752 
IlconControl 790 
IMuldCellCanvas 1063 
INotebook 1093 
ISetCanvas 1149 
ISplitCanvas 1166 
IToolBar 1198 
IToolBarButton 1217 
IToolBarContainer 1225 
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classDefaultStyle (continued) 

IViewPort 1249 
Classes 

IAnimatedButton 8 
IAnimatedButton::Style 17 
IBitmapControl 18 
IBitmapControl::Style 26 
ICanvas 27 
ICanvas::Style 36 
ICircularSlider 37 
ICircularSlider::Style 48 
ICircularSliderNotifyHandler 49 
ICnrAllocator 52 
ICnrBeginEditEvent 55 
ICnrControlList 58 
ICnrDrawBackgroundEvent 60 
ICnrDrawHandler 63 
ICnrDrawItemEvent 69 
ICnrEditEvent 73 
ICnrEditHandler 78 
ICnrEmphasisEvent 83 
ICnrEndEditEvent 86 
ICnrEnterEvent 89 
ICnrEvent 92 
ICnrHandler 95 
ICnrHelpEvent 100 
ICnrMenuHandler 103 
ICnrObjectSet 107 
ICnrQueryDeltaEvent 109 
ICnrReallocStringEvent 112 
ICnrScrollEvent 116 
ICollectionViewComboBox 119 
ICollectionViewConstants 131 
ICollectionViewListBox 133 
IContainerColumn 145 
IContainerControl 163 
IContainerControl::Attribute 218 
IContainerC ontrol:: ColumnCursor 219 
IContainerControl::CompareFn 223 
IContainerControl::FilterFn 225 
IContainerControl::Iterator 227 
IContainerControl::ObjectCursor 229 
IContainerControl:: Style 233 
IContainerControl::TextCursor 234 
IContainerControlNotifyHandler 238 
IContainerObject 241 
ICustomButton 253 
ICustomButton:: Style 263 
ICustomButtonDrawEvent 264 
ICustomButtonDrawHandler 268 


Classes (continued) 

IDDE 272 

IDDEAcknowledgeEvent 276 
IDDEAcknowledgeExecuteEvent 280 
IDDEAcknowledgePokeEvent 283 
IDDEActiveServer 286 
IDDEActiveServerSet 288 
IDDEBeginEvent 290 
IDDEClientAcknowledgeEvent 293 
IDDEClientConversation 297 
IDDEClientEndEvent 311 
IDDEClientHotLinkEvent 314 
IDDEClientHotLinkSet 317 
IDDEDataE vent 319 
IDDEEndEvent 322 
IDDEEvent 325 
IDDEExecuteEvent 328 
IDDEPokeEvent 331 
IDDERequestDataEvent 334 
IDDEServerAcknowledgeEvent 337 
IDDEServerHotEinkEvent 340 
IDDESetAcknowledgelnfoEvent 343 
IDDETopicServer 346 
IDM 358 
IDMCnrltem 367 
IDMEFItem 372 
IDMEvent 377 
IDMHandler 379 
IDMImage 388 
IDMImage::Style 396 
IDMItem 398 
IDMItemProvider 422 
IDMItemProviderFor 426 
IDMMenuItem 429 
IDMMLEItem 434 
IDMOperation 439 
IDMRenderer 448 
IDMSourceBeginEvent 452 
IDMSourceDiscardEvent 455 
IDMSourceEndEvent 458 
IDMSourceHandler 460 
IDMSourceOperation 467 
IDMSourcePrepareEvent 472 
IDMSourcePrintEvent 476 
IDMSourceRenderer 479 
IDMSourceRenderEvent 484 
IDMTargetDropEvent 489 
IDMTargetEndEvent 493 
IDMTargetEnterEvent 497 
IDMTargetEvent 501 
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IDMTargetHandler 504 
IDMTargetHelpEvent 510 
IDMTargetLeaveEvent 512 
IDMTargetOperation 514 
IDMTargetRenderer 519 
IDMTBarButtonltem 525 
IDMToolBarltem 531 
IDrawingCanvas 535 
IDrawingCanvas:: Style 542 
IFileDialog 543 
IFileDialog::Settings 555 
IFileDialog::Style 561 
IFileDialogEvent 563 
IFileDialogFlandler 565 
IFlyOverFlelpFlandler 570 
IFlyText 580 
IFont 584 

IFont::FaceNameCursor 599 
IFont: :PointSizeCursor 602 
IFontDialog 605 
IFontDialog:: Settings 616 
IFontDialog:: Style 620 
IFontDialogHandler 621 
IG3PointArc 625 
IGArc 629 
IGBitmap 634 
IGChord 650 
IGEllipse 653 
IGLine 657 
IGList 661 
IGList: :Cursor 669 
IGPie 673 
IGPolygon 678 
IGPolyline 682 
IGraphic 687 
IGraphicBundle 697 
IGraphicContext 720 
IGraphicPushButton 744 
IGraphicPushButton::Style 754 
IGRectangle 755 
IGRegion 759 
IGString 778 
IlconControl 784 
IIconControl::Style 792 
IlnfoArea 793 

IMM24FramesPerSecondTime 803 
IMM25FramesPerSecondTime 806 
IMM30FramesPerSecondTime 809 
IMMAmpMixer 812 


Classes (continued) 

IMMAudioBuffer 821 
IMMAudioCD 829 
IMMAudioCDContents 846 
IMMAudioCDContents:: Cursor 851 
IMMCDXA 855 
IMMConfigurableAudio 860 
IMMCuePointEvent 870 
IMMDevice 873 
IMMDeviceEvent 905 
IMMDeviceHandler 908 
IMMDigitalVideo 912 
IMMErrorlnfo 933 
IMMFileMedia 937 
IMMHourMinSecFrameTime 944 
IMMHourMinSecTime 949 
IMMMasterAudio 953 
IMMMillisecondTime 958 
IMMMinSecFrameTime 961 
IMMNotify Event 965 
IMMPassDeviceEvent 969 
IMMPlayableDevice 972 
IMMPlayerPanel 983 
IMMPlayerPanelHandler 990 
IMMPositionChangeEvent 995 
IMMRecordable 998 
IMMRemovableMedia 1009 
IMMRemovableMediaFlandler 1016 
IMMSequencer 1019 
IMMSpeed 1024 
IMMTime 1026 

IMMTrackMinSecFrameTime 1035 
IMM Wave Audio 1040 
IMuldCellCanvas 1049 
IMuldCellCanvas::Style 1065 
INotebook 1066 
INotebook::Cursor 1098 
INotebook: :PageSettings 1102 
INotebook::PageSettings::Attribute 1109 
INotebook:: Style 1111 
INotebookDrawItemEvent 1112 
INotebookNotifyHandler 1115 
IPageEvent 1118 
IPageHandle 1121 
IPageFlandler 1123 
IPageFIelpEvent 1127 
IPageRemoveEvent 1130 
IPageSelectEvent 1133 
IRegionHandle 1136 
ISetCanvas 1138 


© IBM Corp. 1992, 1995 


Index 1373 



Classes (continued) 

ISetCanvas:: Style 1155 
ISplitCanvas 1157 
ISplitCanvas: :Style 1169 
IStringGenerator 1171 
IStringGeneratorFn 1175 
IStringGeneratorMemberFn 1178 
IStringGeneratorRefMemberFn 1181 
IToolBar 1184 
IToolBar::FrameCursor 1201 
IToolBar: :Style 1203 
IToolBar: :WindowCursor 1204 
IToolB arB utton 1206 
IToolBarButton::Style 1220 
IToolB arContainer 1221 
IToolBarContainer::Style 1227 
IToolBarFrameWindow 1228 
ITransformMatrix 1233 
IViewPort 1239 
IViewPort:: Style 1251 
clear 

IGRegion 762 
clearClipRegion 

IGraphicContext 741 
clearDefaultTransparentColor 
IToolB arB utton 1213 
client window 
clientHandle 

IDDEClientConversation 300 
clippingRect 

IGString 779 
clipRegion 

IGraphicContext 741 
close 

IMMDevice 886 
closed 

IDMImage 394 
closeDoor 

IMMRemovableMedia 1010 
closeEdit 

IContainerControl 182 
ICnr Allocator 52 
ICnrBeginEditEvent 55 
ICnrControlList 58 
ICnrDrawBackgroundEvent 60 
ICnrDrawHandler 63 
ICnrDrawItemEvent 69 
ICnrEditEvent 73 
ICnrEditHandler 78 


ICnrEmphasisEvent 83 
ICnrEndEditEvent 86 
ICnrEnterEvent 89 
ICnrEvent 92 
ICnrHandler 95 
ICnrHelpEvent 100 
ICnrMenuHandler 103 
ICnrObjectSet 107 
ICnrQueryDeltaEvent 109 
ICnrReallocStringEvent 112 
ICnrScrollEvent 116 
codepageT extFormat 
IDDE 273 
collapse 

IContainerControl 200 
IToolBar 1187 
collapseTree 

IContainerControl 205 
collectionReplaced 

ICollectionViewComboBox 121 
ICollectionViewListBox 135 
ICollection V ie wComboB ox 119 
ICollectionViewConstants 131 
ICollectionViewListBox 133 
color 

color support 1272 
color support, new 1272 
ColorArea 

color support 1272 
column 

ICnrDrawItemEvent 70 
ICnrEditEvent 74 
ICnrHelpEvent 101 
IContainerControl 208 
columnAt 

IContainerControl 179 
columnCount 

IContainerControl 179 
ColumnCursor 

IContainerControl:: ColumnCursor 220 
columnlnfo 

IContainerColumn 157 
columnUnderPoint 

IContainerControl 190 
columnWidth 

IMultiCellCanvas 1058 
combination-box control 
command 

IMMNotify Event 965 
IMMPlayerPanelHandler 992 
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commandN otify Id 
IMMDevice 900 
commands 

IDDEAcknowledgeExecuteEvent 281 
IDDEExecuteEvent 329 
CompareFn 

IContainerControl::CompareFn 223 
completion 

IDMSourceRenderEvent 486 
compressedRMFs 
IDMItem 411 
connectedDeviceld 
IMMDevice 882 
container 

ICnrDrawB ackgroundE vent 61 
ICnrDrawItemEvent 70 
ICnrEditEvent 74 
IContainerColumn 157 
IDM 359 
IDMItem 418 
IDMSourceBeginEvent 453 
IDMTargetDropEvent 490 
IDMTargetEnterEvent 498 
containerAttributes 

IContainerControl 208 
IContainerColumn 145 
IContainerControl 163 
IContainerControl:: Attribute 218 
IContainerControl:: ColumnCursor 219 
IContainerControl:: CompareFn 223 
IContainerControl: :FilterFn 225 
IContainerControl: iterator 227 
IContainerControl: :ObjectCursor 229 
IContainerControl: :Style 233 
IContainerControl: :TextCursor 234 
IContainerControlNotifyHandler 238 
containerFromHandle 

IContainerControl 185 
containerld 

ICnrEvent 93 
IDMCnrltem 369 
IDMSourceBeginEvent 453 
IDMTargetDropEvent 490 
IDMTargetEnterEvent 498 
containerKey 

IContainerControl 208 
containerList 

IContainerControl 209 
containerName 
IDMItem 405 


IContainerObj ect 241 
IDM 359 
IDMOperation 440 
containers 
contains 

IGraphic 690 
containsObject 

IContainerControl 197 
contents 

IDMItem 409 
IMMAudioCD 838 
contentsSize 

IDMItem 409 
contentType 

IMMAudioBuffer 825 
controllnformation 

IMMAudioCDContents 848 
controls 
conventions 

data member names xxii 
file names xxi 
function arguments xxiii 
function return types xxii 
global type names xxii 
maximum characters xxi 
member function names xxii 
numerations xxii 
type names xxii 
conversationCount 

IDDETopicServer 349 
conversationEnded 

IDDEClientConversation 307 
IDDETopicServer 354 
convertToGUIStyle 

IAnimatedButton 12 
IB itmapControl 21 
ICanvas 31 
ICircularSlider 43 
IContainerControl 204 
ICustomButton 257 
IDrawingCanvas 538 
IFileDialog 549 
IFontDialog 610 
IGraphicPushButton 749 
IlconControl 787 
IMultiCellCanvas 1061 
INotebook 1085 
ISetCanvas 1144 
ISplitCanvas 1164 
IToolBar 1189 
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convertToGUIStyle (continued) 
IToolBarButton 1212 
IToolBarContainer 1223 
I ViewPort 1243 
con vertT o W orkspace 

IContainerControl 190 
copy 

IDMOperation 446 
IGBitmap 635 
IMMRecordable 999 
copyable 

IDMItem 419 
copyFromB uffer 

IMM Wave Audio 1040 
copyObjectTo 

IContainerControl 187 
copyToBuffer 

IMM Wave Audio 1041 
country 

IMMAudioCDContents 848 
cpp files, description xxi 
CPP.NDX xxi 
CPP*.DLL 
CPP*.INF xxi 
CPPBRS.NDX xxi 
CPPOOB3.DEF xxi 
CPPOOB3.DLL xxi 
CPPOOC3.LIB xxi 
CPPOOC3I.LIB xxi 
CPPOOC3U.MSG xxi 
CPPOOD3.DEF xxi 
CPPOOD3.DLL xxi 
CPPOOM3.DEF xxi 
CPPOOM3.DLL xxi 
CPPOOU3.DEF xxi 
CPPOOU3.DLL xxi 
createFloatingFrame 
IToolBar 1195 
createT oolB arContainer 
IToolBar 1196 
cueForPlayback 

IMMPlayableDevice 976 
cueForRecording 

IMMRecordable 1000 
cuePoint 

IMMDeviceHandler 909 
cuePointld 

IMMDevice 900 
current 

IContainerControl: :ColumnCursor 219 


current (continued) 

IContainerControl: :ObjectCursor 231 
IContainerControl: :TextCursor 236 
INotebook:: Cursor 1100 
currentB itmaplndex 

IAnimatedButton 11 
currentDrawingPosition 
IGraphicContext 723 
currentEditColumn 

IContainerControl 183 
currentEditMLE 

IContainerControl 183 
currentEditObject 

IContainerControl 183 
currentFont 

IGraphicContext 738 
currentGraphicType 

IGraphicPushButton 747 
currentText 

ICnrBeginEditEvent 56 
ICnrEndEditEvent 87 
ICnrReallocStringEvent 113 
Cursor 

IGList::Cursor 670 
IMMAudioCDContents:: Cursor 851 
INotebook:: Cursor 1098 
cursoredChanged 
ICnrHandler 97 
cursoredObject 

IContainerControl 197 
cursors 

ICustomButton 253 

ICustomButtonDrawEvent 265 
ICustomButton: :Style 263 
ICustomButtonDrawEvent 264 
ICustomButtonDrawHandler 268 
cut 

IMMRecordable 1000 
cutCopy B ufferS ize 

IMM Wave Audio 1041 
cutToB uffer 

IMM Wave Audio 1042 

D 

dat 

IMMDevice 898 
data 

IDDEClientConversation 307 
IDDEDataEvent 320 
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data (continued) 

IDDEServerAcknowledgeEvent 338 
IMMAudioBuffer 823 
data member names, conventions xxii 
data types 

overview xix 
dataAsDate 

IContainerColumn 147 
dataAsIcon 

IContainerColumn 148 
dataAsNumber 

IContainerColumn 148 
dataAsString 

IContainerColumn 148 
dataAsTime 

IContainerColumn 148 
dataAttributes 

IContainerColumn 157 
date 

IContainerColumn 158 
DBCS 
IDDE 272 

IDDEAcknowledgeEvent 276 
IDDEAcknowledgeExecuteEvent 280 
IDDEAcknowledgePokeEvent 283 
IDDEActiveServer 286 
IDDEActiveServerSet 288 
IDDEBeginEvent 290 
IDDEClientAcknowledgeEvent 293 
IDDEClientConversation 297 
IDDEClientEndEvent 311 
IDDEClientHotLinkEvent 314 
IDDEClientHotLinkSet 317 
IDDEDataEvent 319 
IDDEEndEvent 322 
IDDEEvent 325 
IDDEExecuteEvent 328 
IDDEPokeEvent 331 
IDDERequestDataEvent 334 
IDDEServerAcknowledgeEvent 337 
IDDEServerHotLinkEvent 340 
IDDESetAcknowledgelnfoEvent 343 
IDDETopicServer 346 
debugS upport 
IDM 358 
deckCount 

ISetCanvas 1140 
deckOrientation 

ISetCanvas 1141 
deckOrientationld 


deckOrientationld (continued) 
ISetCanvas 1147 
decksBy Group 

ISetCanvas 1149 
decrementU seCount 

IContainerObject 250 
def files 
defaultAttribute 

IContainerControl 174 
defaultB ackgroundColor 
IGraphicContext 724 
defaultB ackgroundMixMode 
IGraphicContext 724 
defaultCell 

IMultiCellCanvas 1058 
defaultDataStyle 

IContainerColumn 148 
defaultDrawOperation 
IGraphicContext 724 
defaultFillColor 

IGraphicContext 724 
defaultFillPattem 

IGraphicContext 725 
defaultGroupPad 
IToolBar 1193 
defaultHeadingStyle 

IContainerColumn 149 
defaultMargin 

IToolBar 1193 
defaultMisfitW idth 
IToolBar 1193 
defaultMixMode 

IGraphicContext 725 
defaultOperation 

IDMTargetEnterEvent 499 
defaultPad 

IToolBar 1193 
defaultPatternOrigin 

IGraphicContext 725 
defaultPenColor 

IGraphicContext 725 
defaultPenEndingStyle 
IGraphicContext 725 
defaultPenJoiningStyle 
IGraphicContext 725 
defaultPenPattern 

IGraphicContext 726 
defaultPenType 

IGraphicContext 726 
defaultPenWidth 
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defaultPenWidth (continued) 
IGraphicContext 726 
defaultPushButton 
ICanvas 29 
defaults ourceHandler 
IDMHandler 379 
defaults ourceRenderer 
IDMRenderer 449 
defaultStyle 

IAnimatedButton 13 
IBitmapControl 21 
ICanvas 31 
ICircularSlider 43 
IContainerControl 204 
ICustomButton 258 
IDMImage 393 
IDrawingCanvas 538 
IFileDialog 549 
IFontDialog 610 
IGraphicPushButton 749 
IlconControl 788 
IMultiCellCanvas 1061 
INotebook 1085 
ISetCanvas 1144 
ISplitCanvas 1164 
IToolBar 1189 
IToolBarButton 1212 
IToolBarContainer 1223 
I ViewPort 1243 
defaultT argetHandler 
IDMHandler 380 
defaultT argetRenderer 
IDMRenderer 450 
defaultText 

IFlyOverHelpHandler 575 
defaultTime 

IMMTime 1032 
defaultTransparentColor 
IToolBarButton 1213 
delay Time 

IFlyOverHelpHandler 577 
deleteAllObjects 

IContainerControl 168 
deletePendingEvents 
IMMDevice 885 
deleteRMF 

IDMItem 412 
deleteSelectedObjects 

IContainerControl 168 


deleteSelection 

IMMRecordable 1001 
deltaReached 

ICnrHandler 97 
dense1 

IGraphicBundle 714 
dense2 

IGraphicBundle 714 
dense3 

IGraphicBundle 714 
dense4 

IGraphicBundle 714 
dense5 

IGraphicBundle 714 
dense6 

IGraphicBundle 714 
dense7 

IGraphicBundle 714 
dense8 

IGraphicBundle 715 
descendentsOf 

IContainerControl 198 
description 

IMMDevice 885 
deselect 

ICollection V iewComboB ox 124 
ICollectionViewListBox 138 
destinationRectangle 

IMMDigital V ideo 922 
destlnvert 

IGBitmap 645 
detailsObjectRectangle 
IContainerControl 190 
detailsTitleRectangle 

IContainerControl 179 
details View 

IContainerControl 210 
detailsViewPortOnWindow 
IContainerControl 195 
details Vie wPortOn Workspace 
IContainerControl 195 
detailsViewSplit 

IContainerControl 179 
detailsViewTitles 

IContainerControl 210 
detailsViewTitlesId 

IContainerControl 213 
device 

IMMCuePointEvent 871 
IMMDeviceEvent 906 
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device (continued) 

IMMNotify Event 966 
IMMPassDeviceEvent 970 
IMMPositionChangeEvent 996 
deviceEvent 

IMMDeviceHandler 909 
deviceEventld 

IMMDevice 900 
deviceld 

IMMDevice 884 
deviceName 

IMMDevice 884 
deviceType 

IMMDevice 885 
IMMPlayerPanel 987 
deviceWindow 

IMMDevice 893 
dialogs 
dibFormat 
IDDE 273 
difFormat 

IDDE 273 
digital Video 

IMMDevice 898 
Direct Manipulation Classes xx 
overview xx 
direction 

IGArc 631 

disableAnimateWhenLatched 
IAnimatedButton 9 
disableAudio 

IMMDevice 874 
disableAutoLatch 

ICustomButton 256 
disableAutoPlay 

IMMAudioCD 830 
disableCaching 

IContainerControl 185 
disableConnector 
IMMDevice 882 
disableContinuousPlay 
IMMAudioCD 830 
disableDataUpdate 

IContainerColumn 149 
IContainerControl 201 
IContainerObject 246 
disableDragDelete 

IToolBarButton 1210 
disableDragDrop 
IToolBar 1186 


disableDragLines 

IMultiCellCanvas 1056 
disableDrawBackground 
IContainerControl 185 
disableDrawItem 

IContainerControl 185 
disableDrop 

IContainerControl 201 
IContainerObject 246 
disabledText 

IlnfoArea 796 
disabledTextld 
IlnfoArea 801 
disableGridLines 

IMultiCellCanvas 1056 
disableHeadingUpdate 

IContainerColumn 149 
disableHeadphones 

IMMMasterAudio 954 
disableLatching 

ICustomButton 256 
disableMisfitFiltering 
IToolBar 1187 
disableMonitoring 

IMMAmpMixer 817 
IMMDigital V ideo 920 
disableSizeToGraphic 

IGraphicPushButton 748 
disableSpeakers 

IMMMasterAudio 955 
disableTitleUpdate 

IContainerControl 169 
discld 

IMMAudioCD 830 
IMMAudioCDContents 848 
discProgramKey 

IMMAudioCD 843 
discTitle 

IMMAudioCD 830 
discTitleKey 

IMMAudioCD 843 
di spatchHandlerE vent 

ICircularSliderNotify Handler 50 
ICnrDrawHandler 67 
ICnrEditHandler 82 
ICnrHandler 99 
ICnrMenuHandler 106 
IContainerControlNotifyHandler 239 
ICustomButtonDrawHandler 269 
IDDEClientConversation 305 
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dispatchHandlerEvent (continued) 
IDDETopicServer 351 
IDMSourceHandler 463 
IDMTargetHandler 507 
IFileDialogHandler 567 
IFlyOverHelpHandler 579 
IFontDialogHandler 623 
IlnfoArea 799 
IMMDeviceHandler 910 
INotebookNotifyHandler 1116 
IPageHandler 1125 
displayBitmapFormat 
IDDE 273 
displayMetafileFormat 
IDDE 273 

displayMetafilePictureFormat 
IDDE 273 
displayTextFormat 
IDDE 274 
display Value 

ICircularSlider 45 
displayWidth 

IContainerColumn 150 
IDM 358 
IDMCnrltem 367 
IDMEFItem 372 
IDMEvent 377 
IDMHandler 379 
IDMImage 388 
IDMImage::Style 396 
IDMItem 398 
IDMItemProvider 422 
IDMItemProviderFor 426 
IDMMenuItem 429 
IDMMLEItem 434 
IDMOperation 439 
IDMRenderer 448 
IDMSourceBeginEvent 452 
IDMSourceDiscardEvent 455 
IDMSourceEndEvent 458 
IDMSourceFlandler 460 
IDMSourceOperation 467 
IDMSourcePrepareEvent 472 
IDMSourcePrintEvent 476 
IDMSourceRenderer 479 
IDMSourceRenderEvent 484 
IDMTargetDropEvent 489 
IDMTargetEndEvent 493 
IDMTargetEnterEvent 497 


IDMTargetEvent 501 
IDMTargetHandler 504 
IDMTargetHelpEvent 510 
IDMTargetLeaveEvent 512 
IDMT argetOperation 514 
IDMTargetRenderer 519 
IDMTBarButtonltem 525 
IDMToolBarltem 531 
doDiscard 

IDMSourceRenderer 482 
doPrint 

IDMSourceRenderer 482 
doRender 

IDMSourceRenderer 482 
doRenderEnd 

IDMSourceRenderer 483 
doRenderPrepare 

IDMSourceRenderer 483 
drag 

IDMOperation 446 
draglnfo 

IDMOperation 445 
dragltem 

IDMSourceEndEvent 459 
IDMSourceRenderEvent 486 
IDMTargetEndEvent 494 
dragLines 

IMultiCellCanvas 1063 
dragWasInterrupted 
IDMOperation 445 
draw 

IGraphicContext 729 
drawBackground 

ICnrDrawHandler 65 
ICustomButtonDrawHandler 269 
drawB order 

ICustomButtonDrawHandler 270 
drawB utton 

ICustomButtonDrawHandler 270 
drawDetailsItem 

ICnrDrawHandler 66 
drawDisabledEmphasis 

ICustomButtonDrawHandler 270 
drawDown 

ICustomButtonDrawEvent 265 
drawForeground 

ICustomButtonDrawHandler 270 
drawlcon 

ICnrDrawHandler 66 
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drawingArea 

ICustomButtonDrawEvent 265 
IDrawingCanvas 535 
IDrawingCanvas:: Style 542 
drawLatched 

ICustomButtonDrawEvent 265 
drawOn 

IG3PointArc 628 
IGArc 631 
IGBitmap 639 
IGChord 651 
IGEllipse 655 
IGLine 659 
IGList 663 
IGPie 675 
IGPolygon 680 
IGPolyline 685 
IGraphic 688 
IGRectangle 757 
IGRegion 762 
IGString 781 
drawOperation 

IGraphicBundle 703 
IGraphicContext 732 
drawTab 

IPageHandler 1125 
drawText 

ICnrDrawHandler 66 
drawTitle 

ICnrDrawHandler 66 
drawTreelcon 

ICnrDrawHandler 66 
drawUp 

ICustomButtonDrawEvent 265 
droplndicator 

IDMTargetEnterEvent 499 
dropOffset 

IDMT argetOperation 515 
dropPosition 

IDMTargetDropEvent 490 
IDMT argetOperation 515 
dropS tatus 

IDMItem 404 

Dynamic Data Exchange Classes xx 
overview xx 

E 

editColumnTitle 

IContainerControl 183 


editContainerT itle 

IContainerControl 183 
editObject 

IContainerControl 183 
element 11 

ITransformMatrix 1235 
element 12 

ITransformMatrix 1235 
element21 

ITransformMatrix 1235 
element22 

ITransformMatrix 1236 
element31 

ITransformMatrix 1236 
element32 

ITransformMatrix 1236 
elementAdded 

ICollectionViewComboBox 121 
ICollectionViewListBox 135 
elementChanged 

ICollectionViewComboBox 122 
ICollectionViewListBox 136 
elementDeleted 

ICollectionViewComboBox 122 
ICollectionViewListBox 136 
elementsChanged 

ICollectionViewComboBox 122 
ICollectionViewListBox 136 
emHeight 

IFontDialog 608 
enableAnimateWhenLatched 
IAnimatedButton 9 
enableAudio 

IMMDevice 875 
enableAutoLatch 

ICustomButton 256 
enableAutoPlay 

IMMAudioCD 831 
enableCaching 

IContainerControl 186 
enableConnector 
IMMDevice 882 
enableContinuousPlay 
IMMAudioCD 831 
enableCopy 

IDMItem 402 
enableDataUpdate 

IContainerColumn 150 
IContainerControl 201 
IContainerObject 246 
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enableDragDelete 

IToolBarButton 1210 
enableDragDrop 
IToolBar 1187 
enableDragDropFor 
IDMHandler 381 
enableDragFrom 
IDMHandler 381 
enableDragLines 

IMultiCellCanvas 1057 
enableDrawB ackground 
IContainerControl 186 
enableDrawItem 

IContainerControl 186 
enableDrop 

IContainerControl 201 
IContainerObject 246 
enableDropOn 

IDMHandler 382 
enableExtendedSelect 

ICollectionViewListBox 139 
enableGridLines 

IMultiCellCanvas 1057 
enableHeadingUpdate 

IContainerColumn 150 
enableHeadphones 

IMMMasterAudio 954 
enableLatching 

ICustomButton 256 
enableLink 

IDMItem 402 
enableMisfitFiltering 
IToolBar 1187 
enableMonitoring 

IMMAmpMixer 817 
IMMDigital Video 921 
enableMove 

IDMItem 403 
enableNotification 
ICircularSlider 42 
IContainerControl 189 
INotebook 1073 
enableS izeT oGraphic 

IGraphicPushButton 748 
enableSpeakers 

IMMMasterAudio 955 
enableTitleUpdate 

IContainerControl 169 
enclosingRect 
IGArc 631 


enclosingRect (continued) 
IGEllipse 655 
IGPie 675 
IGRectangle 757 
end 

IDDEClientConversation 301 
endAllHotLinks 

IDDEClientConversation 309 
endConversation 

IDDETopicServer 348 
endEdit 

ICnrEditHandler 80 
endHotLink 

IDDEClientConversation 303 
endHotLinks 

IDDEClientConversation 303 
endingPoint 

IG3PointArc 627 
IGLine 659 
endOfTrack 

IMMAudioCDContents 848 
endUsingFont 
IFont 588 
enter 

ICnrHandler 97 
enterld 

IContainerControl 213 
enterPressed 

ICnrEnterEvent 90 
entry field control 
errorld 

IMMErrorlnfo 935 
IMMNotify Event 966 
errorText 

IMMNotifyEvent 966 
event 

object xix 
overview xix 
event handler 
eventCode 

IMMDeviceEvent 906 
eventData 

IMMDeviceEvent 906 
executeAcknowledged 

IDDEClientConversation 308 
executeCommands 

IDDEClientConversation 303 
IDDETopicServer 354 
expand 

IContainerControl 201 
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expand (continued) 

IToolBar 1187 
expandForText 

ISetCanvas 1147 
expandTree 

IContainerControl 205 
extended style support 1280 
extendedSelectChangedld 

ICollectionViewListBox 142 
extendedSelection 

IContainerControl 214 
extemalLeading 
IFont 590 
IFontDialog 608 

F 

faceNameAt 
IFont 587 
FaceNameCursor 

IFont: :FaceNameCursor 599 
fastForward 

IMMPlayerPanelHandler 992 
fastForwardButton 

IMMPlayerPanel 984 
fastSpeed 

IMMDigitalVideo 918 
fattrs 

IFont 585 
file 

IDM 359 
file dialog 
IFileDialog 543 
IFileDialog::Settings 555 
IFileDialog::Style 561 
IFileDialogEvent 563 
IFileDialogHandler 565 
fileLength 

IFileDialogEvent 564 
fileName 

IFileDialog 547 
IFileDialog::Settings 558 
IFileDialogEvent 564 
IMMFileMedia 938 
fileNormalSpeed 

IMMDigitalVideo 918 
files 

class library conventions xxi 
hpp files xxi 
ini files xxi 


files (continued) 
lib files xxi 
maximum characters xxi 
fillColor 

IGraphicBundle 700 
IGraphicContext 732 
filled 

IGraphicBundle 715 
fillMode 

IGPolygon 680 
fillPattern 

IGraphicBundle 707 
IGraphicContext 732 
filter 

IContainerControl 184 
IFileDialog 552 
IFileDialogHandler 568 
IToolBar 1196 
FilterFn 

IContainerControl::FilterFn 225 
filterMisfits 

IToolBar 1198 
filterName 

IFileDialogHandler 568 
findRendererFor 

IDMSourceHandler 465 
IDMTargetHandler 509 
findRenderersFor 

IDMSourceHandler 465 
IDMTargetHandler 509 
findTransaction 

IDDEClientConversation 309 
first 

ICnrAllocator 53 

IContainerControl: :ColumnCursor 219 
IContainerControl::ObjectCursor 231 
IContainerControl: :TextCursor 236 
INotebook::Cursor 1100 
firstGraphic 
IGList 664 
firstPage 

INotebook 1078 
fixedWidthOnly 
IFontDialog 613 
fixupChildren 
ICanvas 34 
floatingFrame 

IToolBar 1188 
floatingPosition 
IToolBar 1188 
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floatingTitle 

IToolBar 1188 
flowedView 

IContainerControl 211 
flyHelpText 

IFlyOverHelpHandler 573 
IFlyOverHelpHandler 570 
IFlyText 580 
flyTextControl 

IFlyOverHelpFIandler 574 
AyTextStringTableOffset 

IFlyOverFIelpFlandler 577 
IFont 584 

IGString 781 
font dialog 

IFont::FaceNameCursor 599 
IFont: :PointSizeCursor 602 
IFontDialog 605 
IFontDialog::Settings 616 
IFontDialog: :Style 620 
IFontDialogFIandler 621 
fontFamily 

IFontDialog 608 
fontmetrics 
IFont 586 
fonts 

fontWeight 

IFontDialog 608 
fontWidth 

IFontDialog 609 
fore wardDiag 1 

IGraphicBundle 715 
forewardDiag2 

IGraphicBundle 715 
format 

IDDEEvent 326 
IMMAudioBuffer 825 
IMMConfigurableAudio 862 
IMMSpeed 1025 
frame extensions 
frame window 
FrameCursor 

IToolBar: :FrameCursor 1201 
frames 

IMMHourMinSecFrameTime 944 
IMMMinSecFrameTime 961 
IMMTrackMinSecFrameTime 1035 
framesPerSecond 

IMMHourMinSecFrameTime 944 


frameToolBarContainer 

IToolBarContainer 1222 
full360 

ICircularSlider 45 

function arguments, conventions xxiii 
function return types, conventions xxii 

G 

IG3PointArc 625 
gain 

IMM AmpMixer 814 
IGArc 629 
IGBitmap 634 
IGChord 650 
IGEllipse 653 
generates ourceltems 
IDMCnrltem 369 
IDMEFItem 374 
IDMItem 415 
IDMMenuItem 431 
IDMMLEItem 436 
IDMTBarButtonltem 528 
generates ourceName 
IDMItem 418 
getTableFromDisc 

IMMAudioCD 842 
IGLine 657 
IGList 661 
IGList::Cursor 669 
global names, conventions xxii 
goToEntry 

IMMAudioCD 834 
IGPie 673 
IGPolygon 678 
IGPolyline 682 
IGraphic 687 
graphicAt 

IGList 665 
graphicAtPosition 
IGList 665 
graphicBundle 697 
IGraphic 688 
IGraphicContext 732 
graphicContext 720 

ICustomButtonDrawEvent 266 
IDrawingCanvas 537 
graphicList 

IDrawingCanvas 537 
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IGraphicPushButton 744 
IGraphicPushButton::Style 754 
graphicWindow 

IGraphicPushButton 747 
IGRectangle 755 
IGRegion 759 
gridLines 

IMultiCellCanvas 1063 
group 

IDMItem 419 
groupPad 

ISetCanvas 1142 
IGString 778 

H 

h files, description xxi 
halftone 

IGBitmap 645 
IGraphicBundle 715 
handle 

IGBitmap 635 
IGraphicContext 723 
IMMDigital V ideo 923 
handleAck 

IDDEClientConversation 306 
IDDETopicServer 351 
handleAdvise 

IDDETopicServer 351 
handleCursoredChange 
IContainerObject 243 
handleData 

IDDEClientConversation 306 
handleDrawB ackground 
IContainerControl 211 
handleDrawItem 

IContainerColumn 158 
IContainerControl 211 
handleEventsFor 

ICnrDrawHandler 65 
ICnrEditHandler 80 
ICnrHandler 96 
ICnrMenuHandler 104 
IFileDialogHandler 566 
IFlyOverHelpHandler 574 
IlnfoArea 795 
IMMDeviceHandler 909 
IMMRemovableMediaHandler 1017 
handleExecute 

IDDETopicServer 351 


handlelnitiate 

IDDETopicServer 351 
handlelnitiateAck 

IDDEClientConversation 306 
handlelnuseChange 

IContainerObject 244 
handleOpen 

IContainerObject 244 
handlePoke 

IDDETopicServer 352 
handler 

overview xix 
handleRequest 

IDDETopicServer 352 
handlers for controls 1303 
handleSelectedChange 
IContainerObject 244 
handleTerminate 

IDDEClientConversation 306 
IDDETopicServer 352 
handleTreeCollapse 

IContainerObject 244 
handleTreeExpand 

IContainerObject 244 
handleUnadvise 

IDDETopicServer 352 
hasBackgroundColor 
IGraphicBundle 700 
hasBackgroundMixMode 
IGraphicBundle 699 
hasDragLines 

IMultiCellCanvas 1057 
hasDrawOperation 

IGraphicBundle 703 
hasFillColor 

IGraphicBundle 700 
hasFillPattem 

IGraphicBundle 707 
hasFont 

IGraphicContext 738 
IGString 781 
hasGraphicB undle 
IGraphic 689 
hasGridLines 

IMultiCellCanvas 1057 
hasHorizontal S eparator 
IContainerColumn 150 
haslmage 

IDMItem 403 
hasMixedT argetEmphasis 
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hasMixedTargetEmphasis (continued) Hello World version 6 


IContainerControl 169 

help 


hasMixMode 

ICnrHandler 97 


IGraphicBundle 705 

IPageHandler 1125 

hasNormalT argetEmphasi s 

helpButton 


IContainerControl 169 

IFileDialog 552 


hasOrderedTargetEmphasis 

IFontDialog 613 


IContainerControl 170 

helpld 


hasPattemOrigin 

IContainerColumn 

151 

IGraphicBundle 705 

IContainerObject 

245 

hasPenColor 

help Window 


IGraphicBundle 700 

IPageHelpEvent 

1128 

hasPenEndingStyle 

hide 


IGraphicBundle 711 

IContainerColumn 

151 

hasPenJoiningStyle 

IContainerObj ect 

247 

IGraphicBundle 712 

hideDetailsViewTitles 


hasPenPattem 

IContainerControl 

170 

IGraphicBundle 707 

hideObject 


hasPenType 

IContainerControl 

201 

IGraphicBundle 709 

hideSeparators 


hasPen Width 

IContainerColumn 

151 

IGraphicBundle 710 

hideS ourceEmphasis 


hasTransformMatrix 

IContainerControl 

201 

IGraphic 692 

hideSplitBar 


hasTransparentColor 

IContainerControl 

179 

IGBitmap 636 

hideTitle 


IToolBarButton 1213 

IContainerControl 

170 

hasType 

hideT itleS eparator 


IDMItem 410 

IContainerControl 

170 

hasVerticalSeparator 

hideTreeLine 


IContainerColumn 151 

IContainerControl 

205 

hatched 

hierarchy 


IGraphicBundle 715 

hiliteB ackgroundColor 

hatchedDiag 

INotebook 1069 


IGraphicBundle 715 

hitApertureSize 


headerData 

IGraphicContext 

739 

IMMAudioBuffer 823 

hitPoint 


headinglcon 

IGraphicContext 

739 

IContainerColumn 151 

hollow 


headingText 

IGraphicBundle 716 

IContainerColumn 151 

horizontal 


headphone 

IGraphicBundle 716 

IMMDevice 899 

ISplitCanvas 1166 

Hello World samples 

horizontalDataAlignment 

Hello World version 1 

IContainerColumn 

152 

Hello World version 2 

horizontalDecks 


Hello World version 3 

ISetCanvas 1149 


Hello World version 4 

horizontalHeadingAlignment 

Hello World version 5 

IContainerColumn 

152 
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horizontalScrollBar 
I ViewPort 1240 
horizontalSeparator 

IContainerColumn 159 
hotLinkCount 

IDDEClientConversation 302 
IDDETopicServer 349 
hotLinkEnded 

IDDETopicServer 355 
hotLinklnform 

IDDEClientConversation 308 
hotLinks 

IDDEClientConversation 302 
hotLinkUpdate 

IDDETopicServer 349 
hours 

IMMHourMinSecFrameTime 945 
IMMHourMinSecTime 949 
IMMTime 1027 
hpp files, description xxi 
hundredths 

IMMTime 1027 
hwndAllocation 

IContainerControl 209 

I 

IAnimatedButton 

IAnimatedButton 12 
IBitFlag 
IBitmapControl 

IB itmapControl 19 
ICanvas 

ICanvas 28, 32 
ICheckBox 
ICircularSlider 

ICircularSlider 41 
ICircularS liderN otify Handler 

ICircularSliderNotify Handler 49 
ICnr Allocator 

ICnrAllocator 52 
ICnrB eginEditEvent 

ICnrBeginEditEvent 55 
ICnrControlList 

ICnrControlList 58 
ICnrDrawB ackgroundE vent 

ICnrDrawBackgroundEvent 60 
ICnrDrawHandler 

ICnrDrawHandler 67 


ICnrDrawItemEvent 

ICnrDrawItemEvent 69 
ICnrEditEvent 

ICnrEditEvent 74 
ICnrEditHandler 

ICnrEditHandler 79 
ICnrEmphasisEvent 

ICnrEmphasisEvent 83 
ICnrEndEditEvent 

ICnrEndEditEvent 86 
ICnrEnterEvent 

ICnrEnterEvent 89 
ICnrEvent 

ICnrEvent 92 
ICnrHandler 

ICnrHandler 96 
ICnrHelpEvent 

ICnrHelpEvent 100 
ICnrMenuHandler 

ICnrMenuHandler 105 
ICnrObjectSet 

ICnrObjectSet 107 
ICnrQueryDeltaEvent 

ICnrQueryDeltaEvent 109 
ICnrReallocStringEvent 

ICnrReallocStringEvent 112 
ICnrScrollEvent 

ICnrScrollEvent 116 
ICollection V ie wComboB ox 

ICollectionViewComboBox 123 
ICollection V ie wLi stB ox 

ICollectionViewListBox 137 
icon 

IContainerColumn 161 
IContainerObject 247 
IDM 359 

IGraphicPushButton 747 
IlconControl 787 
IlconControl 784 
IlconControl:: Style 792 
iconRectangle 

IContainerControl 191 
iconSize 

IContainerControl 170 
IContainerColumn 

IContainerColumn 147 
IContainerControl 

IContainerControl 178, 207 
IContainerControlNotifyHandler 

IContainerControlNotifyHandler 238 
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IContainerObject 

IContainerObject 242 
iconText 

IContainerObject 247 
iconView 

IContainerControl 211 
ICurrentApplication 
ICustomButton 

ICustomButton 255, 259 
ICustomButtonDrawEvent 

ICustomButtonDrawEvent 264 
ICustomButtonDrawHandler 

ICustomButtonDrawHandler 268 
id 

IGraphic 691 
IDDEAcknowledgeEvent 

IDDEAcknowledgeEvent 277 
IDDEAcknowledgeExecuteEvent 

IDDEAcknowledgeExecuteEvent 280 
IDDEAcknowledgePokeEvent 

IDDEAcknowledgePokeEvent 283 
IDDEActiveServer 

IDDEActiveServer 286 
IDDEActiveServerSet 

IDDEActiveServerSet 288 
IDDEBeginEvent 

IDDEBeginEvent 290 
IDDEClientAcknowledgeEvent 

IDDEClientAcknowledgeEvent 293 
IDDEClientConversation 

IDDEClientConversation 299 
IDDEClientEndEvent 

IDDEClientEndEvent 311 
IDDEClientHotLinkEvent 

IDDEClientHotLinkEvent 314 
IDDEClientHotLinkS et 

IDDEClientHotLinkSet 317 
IDDEDataEvent 

IDDEDataEvent 319 
IDDEEndEvent 

IDDEEndEvent 322 
IDDEEvent 

IDDEEvent 325 
IDDEExecuteEvent 

IDDEExecuteEvent 328 
IDDEPokeEvent 

IDDEPokeEvent 331 
IDDERequestDataEvent 

IDDERequestDataEvent 334 


IDDEServerAcknowledgeEvent 

IDDEServerAcknowledgeEvent 337 
IDDEServerHotLinkEvent 

IDDEServerHotLinkEvent 340 
IDDESetAcknowledgelnfoEvent 

IDDESetAcknowledgelnfoEvent 343 
IDDETopicServer 

IDDETopicServer 347 
IDMCnrltem 

IDMCnrltem 368 
IDMEFItem 

IDMEFItem 373 
IDMEvent 

IDMEvent 377 
IDMHandler 

IDMHandler 384 
IDMImage 

IDMImage 389 
IDMItem 

IDMItem 400 
IDMItemProvider 

IDMItemProvider 423 
IDMItemProviderFor 

IDMItemProviderFor 427 
IDMMenuItem 

IDMMenuItem 430 
IDMMLEItem 

IDMMLEItem 435 
IDMOperation 

IDMOperation 445 
IDMRenderer 

IDMRenderer 449 
IDMSourceBeginEvent 

IDMSourceBeginEvent 452 
IDMSourceDiscardEvent 

IDMSourceDiscardEvent 455 
IDMSourceEndEvent 

IDMSourceEndEvent 458 
IDMSourceHandler 

IDMSourceHandler 460 
IDMSourceOperation 

IDMSourceOperation 467 
IDMSourcePrepareEvent 

IDMSourcePrepareEvent 473 
IDMSourcePrintEvent 

IDMSourcePrintEvent 476 
IDMSourceRenderer 

IDMSourceRenderer 479 
IDMSourceRenderEvent 

IDMSourceRenderEvent 485 
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IDMTargetDropEvent 

IDMTargetDropEvent 489 
IDMTargetEndEvent 

IDMTargetEndEvent 494 
IDMTargetEnterEvent 

IDMTargetEnterEvent 497 
IDMTargetEvent 

IDMTargetEvent 501 
IDMTargetHandler 

IDMTargetHandler 504 
IDMTargetHelpEvent 

IDMTargetHelpEvent 510 
IDMTargetLeaveEvent 

IDMTargetLeaveEvent 512 
IDMTargetOperation 

IDMTargetOperation 514 
IDMTargetRenderer 

IDMTargetRenderer 519 
IDMTBarButtonltem 

IDMTBarButtonltem 526 
IDMToolBarltem 

IDMToolBarltem 532 
IDrawingC anvas 

IDrawingCanvas 536 
IEvent 

object xix 
overview xix 
IFileDialog 

IFileDialog 544 
IFileDialogEvent 

IFileDialogEvent 563 
IFileDialogFlandler 

IFileDialogHandler 566 
IFlyOverHelpHandler 

IFlyOverHelpHandler 572 
IFlyText 

IFlyText 581 
IFont 

IFont 586 
IFontDialog 

IFontDialog 606 
IFontDialogHandler 

IFontDialogHandler 622 
IFrameWindow 
IG3PointArc 

IG3PointArc 626 
IGArc 

IGArc 630 
IGBitmap 

IGBitmap 637 


IGChord 

IGChord 651 
IGEllipse 

IGEllipse 654 
IGLine 

IGLine 658 
IGList 

IGList 663 

ignored classes and members 1286 
IGPie 

IGPie 674 
IGPolygon 

IGPolygon 679 
IGPolyline 

IGPolyline 683 
IGraphic 

IGraphic 695 
IGraphicBundle 

IGraphicBundle 702 
IGraphicContext 

IGraphicContext 722 
IGraphicPushButton 

IGraphicPushButton 745 
IGRectangle 

IGRectangle 756 
IGRegion 

IGRegion 760 
IGString 

IGString 780 
IHandler 
IlconControl 

IlconControl 785 
IlnfoArea 

IlnfoArea 794 
IListBox 
image 

IDMItem 403 
imageFormat 

IGBitmap 643 
imageOffset 

IDMItem 405 
imageStyle 

IDMSourceOperation 468 
IMenuBar 
IMessageBox 

IMM24FramesPerSecondTime 

IMM24FramesPerSecondTime 803 
IMM25FramesPerSecondTime 

IMM25FramesPerSecondTime 806 
IMM30FramesPerSecondTime 
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IMM30FramesPerSecondTime (continued) 
IMM30FramesPerSecondTime 809 
IMMAmpMixer 

IMMAmpMixer 812 
IMM AudioB uffer 

IMMAudioBuffer 824 
IMMAudioCD 

IMMAudioCD 833, 841 
IMMAudioCDContents 

IMMAudioCDContents 846, 850 
IMMCDXA 

IMMCDXA 855, 858 
IMMConfigurableAudio 

IMMConfigurableAudio 867 
IMMCuePointEvent 

IMMCuePointEvent 870 
IMMDevice 

IMMDevice 892 
IMMDeviceEvent 

IMMDeviceEvent 905 
IMMDeviceHandler 

IMMDeviceHandler 908 
IMMDigitalVideo 

IMMDigitalVideo 914, 929 
immediateDescendentsOf 
IContainerControl 198 
IMMErrorlnfo 

IMMErrorlnfo 934 
IMMFileMedia 

IMMFileMedia 941 
IMMHourMinSecFrameTime 

IMMHourMinSecFrameTime 945 
IMMHourMinSecTime 

IMMHourMinSecTime 950 
IMMMasterAudio 

IMMMasterAudio 953 
IMMMillisecondTime 

IMMMillisecondTime 958 
IMMMinSecFrameTime 

IMMMinSecFrameTime 962 
IMMNotifyEvent 

IMMNotify Event 966 
IMMPassDeviceEvent 

IMMPassDeviceEvent 969 
IMMPlayableDevice 

IMMPlayableDevice 980 
IMMPlayerPanel 

IMMPlayerPanel 985 
IMMPlayerPanelHandler 

IMMPlayerPanelHandler 991 


IMMPositionChangeEvent 

IMMPositionChangeEvent 995 
IMMRecordable 

IMMRecordable 1006 
IMMRemovableMedia 

IMMRemovableMedia 1013 
IMMRemovableMediaFlandler 

IMMRemovableMediaFlandler 1016 
IMMSequencer 

IMMSequencer 1019, 1021 
IMMSpeed 

IMMSpeed 1024 
IMMTime 

IMMTime 1027 
IMMTrackMinSecFrameTime 

IMMTrackMinSecFrameTime 1036 
IMMW ave Audio 

IMMW ave Audio 1044, 1046 
IMultiCellCanvas 

IMultiCellCanvas 1055 
IMultiLineEdit 
inactiveText 

IlnfoArea 796 
inactiveTextld 
IlnfoArea 801 
includeEAS 

IFileDialog 552 
inConversation 

IDDEClientConversation 300 
incrementUseCount 

IContainerObject 250 
IlnfoArea 793 
information area 
informationFor 
IlnfoArea 799 
informSourceOfCompletion 
IDMTargetRenderer 520 
informTargetOfCompletion 
IDMSourceRenderer 480 
initialDelayTime 

IFlyOverHelpHandler 578 
initialDrive 

IFileDialog: :Settings 558 
initialFileType 

IFileDialog: :Settings 558 
initialize 

IContainerControl 184 
IContainerObject 250 
IToolBar 1196 
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initialized 

ICnr Allocator 53 
ini files, description xxi 
INotebook 

INotebook 1072 
IN otebookDrawItemE vent 

INotebookDrawItemEvent 1112 
IN otebookN otify Handler 

IN otebookN otify Handler 1115 
insertPoint 

IGPolyline 684 
instanceFor 

IDMT argetOperation 516 
intermediatePoint 
IG3PointArc 627 
internalLeading 
IFont 590 
inuseChanged 

ICnrHandler 97 
invalidate 

IContainerColumn 157 
IContainerControl:: ColumnCursor 221 
IContainerControl: :ObjectCursor 231 
IContainerControl: iTextCursor 236 
IFont: :FaceNameCursor 600 
IFont:: Points izeCursor 603 
IGList::Cursor 670 
IMMAudioCDContents:: Cursor 852 
IN otebook:: Cursor 1099 
IToolBar::FrameCursor 1202 
IToolBar::WindowCursor 1205 
invert 

IGBitmap 645 
invisible 

IContainerColumn 159 
IPageEvent 

IPageEvent 1118 
IPageHandle 

IPageHandle 1121 
IPageHandler 

IPageHandler 1124 
IPageHelpEvent 

IPageHelpEvent 1127 
IPageRemoveEvent 

IPageRemoveEvent 1131 
IPageSelectEvent 

IPageSelectEvent 1133 
IPopUpMenu 
IPushButton 
IRadioButton 


IRegionHandle 

IRegionHandle 1136 
isAboveFirst 

IDMTargetEnterEvent 498 
isAckPositive 

IDDEAcknowledgeEvent 277 
isAckRequested 

IDDEClientHotLinkEvent 315 
IDDEDataEvent 320 
is AckT oB eginHotLink 

IDDEClientAcknowledgeEvent 294 
isAckToEndHotLink 

IDDEClientAcknowledgeEvent 294 
isAckToHotLinkUpdate 

IDDEServerAcknowledgeEvent 338 
isAckToRequestData 

IDDEClientAcknowledgeEvent 294 
isAcquired 

ICnrEmphasisEvent 84 
IMMDevice 889 
isAnimatedWhenLatched 
IAnimatedButton 9 
isAnimationStarted 
IAnimatedButton 9 
isApplicationBusy 

IDDEAcknowledgeEvent 277 
isAttribute 

IContainerObject 251 
isAudioEnabled 

IMMDevice 875 
isAutoLatchEnabled 
ICustomButton 256 
isAutoPlayEnabled 
IMMAudioCD 831 
isAutoSize 

INotebook: :PageSettings 1103 
isAvailable 

IMMErrorlnfo 935 
isBitmap 

IFont 593 
isBitmapOnly 
IFont 588 
isBitmapVisible 

IToolBarButton 1214 
isBold 

IFont 594 
isButtonEnabled 

ICustomButtonDrawEvent 266 
isCachingEnabled 

IContainerControl 186 


© IBM Corp. 1992, 1995 


Index 


1391 



isCaseSensitive 

IDDEActiveServer 287 
IDDEClientConversation 300 
isClippingRectSet 
IGString 779 
isCloseOnDestroy 
IMMDevice 886 
isCollapsed 

IContainerControl 193 
isColumnExpandable 

IMultiCellCanvas 1058 
isColumnRight 

IContainerControl 180 
isConnectionSupported 
IMMDevice 883 
isConnectorEnabled 
IMMDevice 883 
isContainer 

IDMItem 405 
isContainerControl 
IDMHandler 384 
isContinuousPlayEnabled 
IMMAudioCD 831 
isCursored 

IContainerControl 193 
isDataFromHotLink 

IDDEDataEvent 320 
isDatalString 

ICnrEditHandler 80 
isDataRequested 

IDDEClientHotLinkEvent 315 
IDDEServerHotLinkEvent 341 
isDate 

IContainerColumn 152 
isDefaultTransparentColorSet 
IToolBarButton 1213 
isDetailsData 

ICnrEditEvent 74 
isDetailsView 

IContainerControl 181 
isDialogTemplateSet 

IFileDialog:: Settings 556 
isDragAfter 

IDMTargetEnterEvent 498 
isDrawBackgroundEnabled 
IContainerControl 186 
isDrawItemEnabled 

IContainerControl 186 
isDropOnAble 

IContainerControl 194 


isDropOnAble (continued) 
IContainerObject 247 
isEmpty 

IGList 665 
INotebook 1080 
isEqual 

IContainerControl: :CompareFn 224 
ISetCanvas 

ISetCanvas 1139 
isExpanded 

IContainerControl 194 
IToolBar 1187 
isExtendedSelection 

IContainerControl 170 
isFixed 

IFont 593 
isFlowed 

IContainerControl 181 
isFlowedN ameV iew 

IContainerControl 181 
isFlowedTextView 

IContainerControl 181 
isGainingUse 

IMMPassDeviceEvent 970 
isGroup 

IDMItem 405 
isHeadinglconHandle 

IContainerColumn 152 
isHeadingString 

IContainerColumn 152 
isHeadingWriteable 

IContainerColumn 152 
isHitSelectable 
IGraphic 690 
isHitSelected 
IGraphic 690 
isHorizontal 

ICnrScrollEvent 117 
isIconHandle 

IContainerColumn 153 
isIconView 

IContainerControl 181 
isIGList 

IGList 665 
isInUse 

IContainerControl 194 
IContainerObject 247 
isltalic 

IFont 594 
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isLatched 

ICustomButton 257 
isLatchedBackgroundColorHalftone 
ICustomButton 254 
isLatchingEnabled 

ICustomButton 257 
isLeftDetails 

ICnrEditEvent 75 
ICnrScrollEvent 117 
isLeftDetailsHeading 
ICnrEditEvent 75 
ISlider 
isMajorTab 

INotebook: :PageSettings 1106 
isMediaPresent 

IMMRemovableMedia 1010 
isMemberOf 

IContainerControl::FilterFn 226 
isMessageUnderstood 

IDDEAcknowledgeEvent 277 
isMinorTab 

INotebook: :PageSettings 1106 
isMisfitFilteringEnabled 
IToolBar 1188 
isModeless 

IFileDialog 548 
IFontDialog 609 
isMonitoringEnabled 
IMMAmpMixer 818 
IMMDigital Video 921 
isMove Valid 

IContainerControl 187 
isMultipleSelection 

IContainerControl 170 
isNameView 

IContainerControl 181 
isNonPropOnly 
IFont 588 
isNumber 

IContainerColumn 153 
isOnRemovableMedia 
IDMItem 406 
isOpen 

IContainerObject 247 
IDMItem 406 
IMMDevice 886 
isOpenDialog 

IFileDialog:: Settings 558 
isOpenStringV alid 

IMMAmpMixer 819 


isOpenStringValid (continued) 
IMMAudioCD 841 
IMMCDXA 858 
IMMDevice 894 
IMMDigital V ideo 930 
IMMSequencer 1022 
IMM Wave Audio 1047 
isOutline 

IFont 594 
isPacingRequested 

IDDEServerHotLinkEvent 341 
isPlayingForward 

IMMDigital Video 915 
ISplitCanvas 

ISplitCanvas 1161 
isPositionSet 

IFileDialog:: Settings 556 
isReadOnly 

IMMFileMedia 938 
isReference 

IDMItem 406 
isRefreshOn 

IContainerControl 196 
IContainerObject 247 
isRightDetails 

ICnrEditEvent 75 
ICnrScrollEvent 117 
isRightDetailsHeading 
ICnrEditEvent 75 
isRowExpandable 

IMultiCellCanvas 1059 
isSelected 

IContainerControl 194 
isShowingMinilcons 

IContainerControl 182 
isSingleSelection 

IContainerControl 171 
isSizeToGraphic 

IGraphicPushButton 749 
isSource 

IContainerControl 194 
isStandardFormat 

IToolBarButton 1210 
isStatusTextOn 

INotebook: :PageSettings 1105 
isStrikeout 
IFont 594 
isString 

IContainerColumn 153 
isStyle 
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isStyle (continued) 

IDMT argetOperation 515 
isTabStop 

ICanvas 29 
isTarget 

IContainerControl 194 
isT argetTheS ource 
IDMItem 411 
IStaticText 
isTextView 

IContainerControl 182 
isTextVisible 

IToolBarButton 1214 
isTime 

IContainerColumn 153 
isTitleSeparatorVisible 
IContainerControl 171 
isTitleVisible 

IContainerControl 171 
isTitleWindow 

ICnrEditEvent 75 
isTitleWriteable 

IContainerControl 171 
isTreelconView 

IContainerControl 182 
isTreeNameView 

IContainerControl 182 
isTreeTextView 

IContainerControl 182 
isTreeView 

IContainerControl 182 
IStringGenerator 

IStringGenerator 1172 
IStringGeneratorFn 

IStringGeneratorFn 1176 
IStringGeneratorMemberFn 

IStringGeneratorMemberFn 1179 
IStringGeneratorRefMemberFn 

IStringGeneratorRefMemberFn 1182 
isUnderscore 
IFont 594 
is Valid 

IContainerControl: :ColumnCursor 222 
IContainerControl: :ObjectCursor 231 
IContainerControl: :TextCursor 236 
IFont: :FaceNameCursor 600 
IFont: :PointSizeCursor 603 
IGList::Cursor 671 
IMMAudioCDContents 849 
IMM AudioCDContents:: Cursor 852 


is Valid (continued) 

IMMTime 1028 
INotebook:: Cursor 1099 
IToolBar::FrameCursor 1202 
IToolBar::WindowCursor 1205 
isVectorOnly 
IFont 588 
is Vertical 

ICnrScrollEvent 117 
isVisible 

IContainerColumn 153 
IContainerControl 192, 194 
IContainerObject 248 
isWriteable 

IContainerColumn 153 
IContainerControl 195 
IContainerObject 248 
item 

IDDEEvent 326 
IDMOperation 441 
itemCapability 

IMMDevice 894 
itemChangedld 

ICollectionViewComboBox 128 
ICollectionViewListBox 143 
itemld 

ICnrDrawB ackgroundE vent 61 
INotebookDrawItemEvent 1113 
itemPresSpaceHandle 

ICnrDrawB ackgroundE vent 61 
ICnrDrawItemEvent 70 
itemRect 

ICnrDrawB ackgroundE vent 61 
ICnrDrawItemEvent 70 
items 

ICollection V ie wComboB ox 120 
ICollectionViewListBox 134 
itemsld 

ICollection V iewComboB ox 128 
ICollectionViewListBox 143 
itemStatus 

IMMDevice 894 
itemType 

ICnrDrawItemEvent 71 
Iterator 

IContainerControl:: Iterator 227 
IThread 
IToolBar 

IToolBar 1185 
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IToolBarButton 

IToolBarButton 1208 
IToolB arContainer 

IToolB arContainer 1222 
IToolB arFrame Window 

IToolB arFrame Window 1229 
ITransformMatrix 

ITransformMatrix 1234 
I ViewPort 

I ViewPort 1241 

J 

jumpToPointer 

ICircularSlider 46 
justifyData 

IContainerColumn 153 
justify Pleading 

IContainerColumn 154 

L 

label 

ICircularSlider 46 
last 

IContainerControl:: ColumnCursor 220 
IContainerControl: :ObjectCursor 232 
IContainerControl: :TextCursor 237 
IN otebook:: Cursor 1100 
lastError 

IMMDevice 893 
lastGraphic 
IGList 665 
lastPage 

INotebook 1078 
latch 

IAnimatedButton 10 
ICustomButton 257 
latchable 

ICustomButton 261 
latchedBackgroundColor 
ICustomButton 254 
latchedBitmap 

IToolBarButton 1207 
latchedForegroundColor 
ICustomButton 254 
latchld 

ICustomButton 260 
layout 

ICanvas 34 


layout (continued) 

IMultiCellCanvas 1062 
ISetCanvas 1146 
ISplitCanvas 1165 
I ViewPort 1246 
layoutSize 

ICanvas 34 
leftAlign 

ISetCanvas 1149 
length 

IMMAudioBuffer 823 
IMMPlayableDevice 973 
lib files, description xxi 
lineCount 

IlnfoArea 795 
lineSpacing 

IContainerControl 171 
link 

IDMOperation 446 
linkable 

IDMItem 420 
linkFormat 
IDDE 274 
list box control 
listDelete 

ICollection V ie wConstants 131 
listDelete All 

ICollection V ie wConstants 132 
listEnd 

ICollection V ie wConstants 132 
listError 

ICollection Vie wConstants 132 
listlnsert 

ICollection Vie wConstants 132 
listMemoryError 

ICollection Vie wConstants 132 
listNone 

ICollection V ie wConstants 132 
load 

IMMFileMedia 938 
loadBitmap 

IGBitmap 644 
loadOnThread 

IMMFileMedia 939 
location 

IToolB ar 1194 
IToolBarContainer 1222 
lockDoor 

IMMRemovableMedia 1010 
longHelpText 
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longHelpText (continued) 

IFlyOverHelpHandler 573 
longStringT ableOffset 

IFlyOverHelpHandler 577 
longTextControl 

IFlyOverHelpHandler 574 


maxLowercaseDescender 
IFont 591 
maxSize 

IFont 591 
maxUppercaseSize 
IFont 591 
MBCS 


M 

main window 
majorTab 

INotebook: :PageSettings 1108 
maj orT abB ackgroundColor 
INotebook 1069 
maj orT abB ackgroundColorld 
INotebook 1090 
maj orTabForegroundColor 
INotebook 1069 
maj orTabForegroundColorld 


INotebook 

1091 

majorTabsBottom 

INotebook 

1093 

majorTabsLeft 


INotebook 

1093 

majorTabsRight 


INotebook 

1093 

majorTabsTop 


INotebook 

1093 

mappingMode 



IGraphicContext 740 
margin 

ISetCanvas 1142 
marginSize 

IGraphicPushButton 749 
matchForMnemonic 
ICanvas 30 
matchingRMFs 
IDMItem 412 
maxAscender 
IFont 591 
maxCharHeight 
IFont 591 
maxDescender 
IFont 591 
maximumSpeed 

IMMDigital Video 918 
maximumWindows 

IMMDigital V ideo 923 
maxLowercaseAscender 
IFont 591 


mediaLoaded 

IMMRemovableMediaHandler 1017 
mediaLoadedld 

IMMRemovableMedia 1014 
mediaType 

IMMAudioBuffer 825 
mediaUnloaded 

IMMRemovableMediaHandler 1017 
member function names, conventions xxii 
menu bar 
menuEnded 

ICnrMenuHandler 106 
IlnfoArea 800 
menultem 
IDM 359 
menus 

menuSelected 
IlnfoArea 800 
mergeCopy 

IGBitmap 645 
mergePaint 

IGBitmap 646 
message box 
metafileFormat 
IDDE 274 
metafilePictureFormat 
IDDE 274 
microphone 

IMMDevice 899 
midpoint 

ICircularSlider 46 
miniicons 

IContainerControl 211 
minimumSpeed 

IMMDigital Video 919 
minorTab 

INotebook: :PageSettings 1108 
minorTabB ackgroundColor 
INotebook 1069 
minorT abB ackgroundColorld 
INotebook 1091 
minorT abForegroundColor 
INotebook 1069 
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rainorTabForegroundColorld 
INotebook 1091 
rainTextWidth 
IFont 592 
minutes 

IMMHourMinSecFrameTime 945 
IMMHourMinSecTime 949 
IMMMinSecFrameTime 961 
IMMTime 1027 

IMMTrackMinSecFrameTime 1035 
missingText 

IlnfoArea 797 
missingTextld 
IlnfoArea 801 
mixedTargetEmphasis 

IContainerControl 211 
mixMode 

IGraphicBundle 705 
IGraphicContext 732 
MLE 

mleHandler 

ICnrEditFlandler 81 
IMM24FramesPerSecondTime 803 
IMM25FramesPerSecondTime 806 
IMM30FramesPerSecondTime 809 
IMMAmpMixer 812 
IMMAudioBuffer 821 
IMMAudioCD 829 
IMMAudioCDContents 846 
IMMAudioCDContents::Cursor 851 
IMMCDXA 855 
IMMConfigurableAudio 860 
IMMCuePointEvent 870 
IMMDevice 873 
IMMDeviceEvent 905 
IMMDeviceHandler 908 
IMMDigitalVideo 912 
IMMErrorlnfo 933 
IMMFileMedia 937 
IMMHourMinSecFrameTime 944 
IMMHourMinSecTime 949 
IMMMasterAudio 953 
IMMMillisecondTime 958 
IMMMinSecFrameTime 961 
IMMNotifyEvent 965 
IMMPassDeviceEvent 969 
IMMPlayableDevice 972 
IMMPlayerPanel 983 
IMMPlayerPanelHandler 990 
IMMPositionChangeEvent 995 


IMMRecordable 998 
IMMRemovableMedia 1009 
IMMRemovableMediaHandler 1016 
IMMSequencer 1019 
IMMSpeed 1024 
IMMTime 1026 

IMMTrackMinSecFrameTime 1035 

IMM Wave Audio 1040 

mode 

IMMDevice 885 
modeless 

IFileDialog 552 
IFontDialog 613 
modelessResults 

IFileDialogHandler 568 
IFontDialogHandler 623 
monitor 

IMMDevice 899 
monitorHandle 

IMMDigitalVideo 921 
move 

IDMOperation 446 
moveable 

IDMItem 420 
moveAfter 

IToolBar 1191 
moveBefore 

IToolBar 1192 
moveBy 

IGRegion 775 
movelconTo 

IContainerControl 191 
moveObjectTo 

IContainerControl 189 
moveSizeTo 

IBitmapControl 22 
IGraphicPushButton 750 
IlconControl 788 
ISetCanvas 1145 
moveTo 

IGBitmap 636 
IGString 782 
moveToFirst 

IToolBar 1192 
moveToLast 

IToolBar 1192 
IMultiCellCanvas 1049 
IMultiCellCanvas::Style 1065 
multiLineEdit 

ICnrEditHandler 81 
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multimedia books 1363 
Multimedia Classes xx 
overview xx 
multiple-cell canvas 
multiple-line edit (MLE) fields 
multipleSelection 

IContainerControl 215 
multiSelection 

IFileDialog 553 

N 

name 

IFont 593 
name View 

IContainerControl 212 
naming conventions 

data member names xxii 
file names xxi 
function arguments xxiii 
function return types xxii 
global type names xxii 
maximum characters xxi 
member function names xxii 
numerations xxii 
type names xxii 
national language support 
nativeRF 

IDMItem 413 
nativeRM 

IDMItem 413 
nativeRMF 

IDMItem 413 
newText 

ICnrEndEditEvent 87 
ICnrReallocStringEvent 113 
newTextSize 

ICnrReallocStringEvent 113 
next 

ICnr Allocator 53 

IContainerControl: :ColumnCursor 220 
IContainerControl: :ObjectCursor 232 
IContainerControl: :TextCursor 237 
INotebook:: Cursor 1100 
nextAvailable 

ICnr Allocator 53 
nextPage 

INotebook 1078 
nlsCompare 

IContainerControl 204 


noAttribute 

INotebook: :PageSettings 1108 
noDragDelete 

IToolBarButton 1217 
noDragDrop 

IToolBar 1198 
noHorizontalS crollB ar 
I ViewPort 1249 
nominalPointSize 
IFontDialog 609 
none 

IDMItem 419 
normal 

IGBitmap 646 
normalSpeed 

IMMDigital Video 919 
noSelection 

ICollection V iewComboB ox 129 
ICollectionViewListBox 143 
noSharedObjects 

IContainerControl 215 
noSourceRendering 

IDMSourcePrepareEvent 474 
noSplitBars 

ISplitCanvas 1167 
noStyle 

IDMImage 394 
IFileDialog 553 
IFontDialog 613 
noSynthesize 

IFontDialog 613 
notebook 1066 
IPageEvent 1119 
IPageHelpEvent 1128 
IPageRemoveEvent 1131 
IPageS electE vent 1134 
INotebook:: Cursor 1098 
INotebook: :PageSettings 1102 
INotebook:: PageS ettings:: Attribute 1109 
INotebook:: Style 1111 
INotebookDrawItemEvent 1112 
INotebookNotifyHandler 1115 
notebookSize 

INotebook 1080 
noTicks 

ICircularSlider 46 
notSourceErase 
IGBitmap 646 
noVerticalScrollBar 
I ViewPort 1249 
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noViewWindowFill 
I ViewPort 1249 
number 

IContainerColumn 159 
numberOfColumnChanges 
IContainerControl 187 
numberOfEntries 

IMMAudioCDContents 847 
numberOfGraphics 
IGList 665 
numberOfltems 

IDMOperation 441 
numberOfObj ectChanges 
IContainerControl 187 
numberOfPoints 
IDMImage 391 
IGPolyline 684 
numberOfRenderers 
IDMHandler 385 
IDMSourceHandler 462 
IDMTargetHandler 506 
numberOfT racks 

IMMAudioCD 831 
IMMAudioCDContents 849 
numerations, conventions xxii 

O 

object 

ICnrDrawItemEvent 71 
ICnrEditEvent 75 
ICnrEmphasisEvent 84 
ICnrEnterEvent 90 
ICnrHelpEvent 101 
IDMEFItem 374 
IDMItem 409 
IDMMLEItem 436 
IDMSourceBeginEvent 453 
IDMTargetDropEvent 490 
IDMTargetEnterEvent 498 
objectAt 

IContainerControl 198 
objectCopy 

IContainerObject 245 
objectCount 

IContainerControl 198 
ObjectCursor 

IContainerControl:: Obj ectCursor 229 
objectList 

IContainerControl 198 


objectUnderPoint 

IContainerControl 191 
obsolete classes and members 1286 
oemT extFormat 
IDDE 274 
offset 

IDMSourceBeginEvent 453 
ok 

IFileDialog 551 
IFontDialog 612 
okButtonText 

IFileDialog:: Settings 556 
open 

IDMItem 419 
IMMDevice 887, 896 
openDoor 

IMMRemovableMedia 1011 
openOnThread 

IMMDevice 887, 896 
openStatus 

IMMDevice 897 
operation 

IDMOperation 442 
IDMSourceOperation 469 
IDMTargetHelpEvent 511 
operationFronr 

IDMSourceOperation 469 
operator - 

IMMTime 1029 

IMMTrackMinSecFrameTime 1038 
operator — 

IMMAudioCDContents:: Cursor 852 
operator -= 

IGRegion 767, 772 
IMMTime 1029 

IMMTrackMinSecFrameTime 1038 
operator != 

IG3PointArc 625 
IGArc 630 
IGEllipse 654 
IGFine 657 
IGPie 674 
IGPolygon 679 
IGPolyline 683 
IGraphic 694 
IGraphicBundle 702 
IGRectangle 756 
IGString 779 
IMMTime 1029 
ITransformMatrix 1233 
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operator &= 

IGRegion 764, 770 
operator + 

IMMTime 1029 

IMMTrackMinSecFrameTime 1038 
operator ++ 

IMMAudioCDContents:: Cursor 852 
operator += 

IGRegion 766, 771 
IMMTime 1029 

IMMTrackMinSecFrameTime 1038 
operator < 

IMMTime 1030 
operator <= 

IMMTime 1030 
operator = 

IDMImage 390 

IDMItem 401 

IFont 587 

IG3PointArc 626 

IGArc 630 

IGEllipse 655 

IGLine 658 

IGPie 675 

IGPolygon 680 

IGPolyline 683 

IGraphic 695 

IGraphicBundle 703 

IGRectangle 756 

IGRegion 761 

IGString 780 

IMMAudioBuffer 824 

IMMAudioCDContents 847 

IMMAudioCDContents:: Cursor 852 

IMMTime 1028 

IMMTrackMinSecFrameTime 1037 
IStringGenerator 1172 
ITransformMatrix 1235 
operator == 

IContainerC ontrol 178 
IContainerObject 245 
IG3PointArc 626 
IGArc 630 
IGEllipse 654 
IGLine 658 
IGPie 674 
IGPolygon 679 
IGPolyline 683 
IGraphic 694 
IGraphicBundle 702 


operator == (continued) 

IGRectangle 756 
IGString 779 
IMMTime 1030 
ITransformMatrix 1233 
operator > 

IMMTime 1030 
operator >= 

IMMTime 1030 
operator 

IGRegion 768, 774 
operator const char * 

IMMErrorlnfo 935 
operator const IRegionHandle 
IGRegion 761 
operator delete 

IContainerObject 245 
operator new 

IContainerObject 245 
operator unsigned long 

IMM24FramesPerSecondTime 804 
IMM25FramesPerSecondTime 807 
IMM30FramesPerSecondTime 810 
IMMHourMinSecFrameTime 946 
IMMHourMinSecTime 950 
IMMMillisecondTime 959 
IMMMinSecFrameTime 962 
IMMTime 1028 

IMMTrackMinSecFrameTime 1037 
operator Value 

IPageHandle 1122 
orderedT argetEmphasis 
IContainerControl 212 
ordinal 

IMMHourMinSecFrameTime 946 
IMMHourMinSecTime 951 
IMMTime 1031 
orientation 

INotebook 1074 
ISplitCanvas 1163 
orientationld 

INotebook 1091 
ISplitCanvas 1166 
origDefaultButtonHandle 
ICanvas 30 
other 

IMMDevice 899 
outstandingTransactionCount 

IDDEClientConversation 300 
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overlay 

IMMDevice 899 
owner 

IMMAudioCDContents 849 

P 

packEven 


ISetCanvas 

1149 

packExpanded 


ISetCanvas 

1150 

packTight 


ISetCanvas 

1150 

packType 


ISetCanvas 

1142 

pad 


ISetCanvas 

1142 


page 

INotebookDrawItemEvent 1113 
pageB ackgroundColor 
INotebook 1069 
pageB ackgroundColorld 
INotebook 1091 
IPageEvent 1118 
pageHandle 1121 
IPageEvent 1119 
IPageHelpEvent 1129 
IPageSelectEvent 1134 
IPageHandler 1123 
IPageHelpEvent 1127 
IPageRemo veEvent 1130 
IPageSelectEvent 1133 
pageSettings 

INotebook 1077 
INotebook: :PageSettings 1103 
pageSize 

IGraphicContext 728 
INotebook 1080 
pagesToEnd 

INotebook 1081 
pagesToMajorTab 
INotebook 1081 
pagesT oMinorT ab 
INotebook 1081 
page Window 

IPageRemo veEvent 1131 
paletteFormat 
IDDE 274 
parentObject 

IContainerControl 198 


passDevice 

IMMDeviceHandler 909 
IMMRemovableMediaHandler 1017 
passDeviceld 

IMMDevice 900 
passEventToOwner 
ICanvas 32 
paste 

IMMRecordable 1001 
pasteFromB uffer 

IMM Wave Audio 1042 
pasteToBuffer 

IMM Wave Audio 1043 
patternCopy 

IGBitmap 646 
patternlnvert 

IGBitmap 646 
patternOrigin 

IGraphicBundle 706 
IGraphicContext 733 
patternPaint 

IGBitmap 646 
pause 

IMMAudioCD 835 
IMMPlayableDevice 975 
IMMPlayerPanelHandler 992 
pauseButton 

IMMPlayerPanel 984 
penColor 

IGraphicBundle 701 
IGraphicContext 733 
penEndingStyle 

IGraphicBundle 711 
IGraphicContext 733 
penJoiningStyle 

IGraphicBundle 712 
IGraphicContext 733 
penPattern 

IGraphicBundle 708 
IGraphicContext 734 
penType 

IGraphicBundle 709 
IGraphicContext 734 
pen Width 

IGraphicBundle 710 
IGraphicContext 734 
pitch 

IMMAmpMixer 814 
plainText 
IDM 360 
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play 

IMMAudioCD 835 
IMMPlayableDevice 976 
IMMPlayerPanelHandler 992 
playableDevice 

IMMPlayerPanel 987 
playAt 

IMMDigital Video 915 
playButton 

IMMPlayerPanel 985 
playDigital 

IMMDigital V ideo 930 
playFast 

IMMDigital Video 916 
playScan 

IMMDigital Video 916 
playSlow 

IMMDigital Video 917 
point 

IGPolyline 684 
pointArray 

IDMImage 391 
IGPolyline 684 
pointer 

IDMImage 391 
pointerOffset 

IDMImage 391 
IDMSourceOperation 470 
pointSize 
IFont 593 
IFontDialog 609 
pointSizeAt 
IFont 588 
PointSizeCursor 

IFont: :PointSizeCursor 602 
pokeAcknowledged 

IDDEClientConversation 308 
pokeData 

IDDEClientConversation 304 
IDDETopicServer 355 
pokedData 

IDDEAcknowledgePokeEvent 284 
IDDEPokeEvent 332 
polygon 

IDMImage 394 
polygonTabs 

INotebook 1094 
pop-up menu 
popupMenuObject 

ICnrMenuHandler 104 


portability 

publications 1362 
position 

IDMOperation 443 
IDMSourceBeginEvent 453 
IDMTargetEnterEvent 499 
IFileDialog::Settings 556 
IGBitmap 636 
IGString 782 
IMMCuePointEvent 871 
IMMPlayableDevice 974 
IMMPositionChangeEvent 996 
ISetCanvas 1145 
positionChange 

IMMDeviceHandler 910 
positionChangeld 
IMMDevice 901 
positionRelativeTo 

IDMT argetOperation 515 
positionTimerld 

IMMAudioCD 844 
positionViewWindow 
I ViewPort 1246 
preload 

IFileDialog 553 
prepare 

IDMItem 419 
prepareAtSource 

IDMTargetRenderer 523 
prerollTime 

IMMDevice 888 
prerollType 

IMMDevice 888 
Presentation Manager messages 
pressedOK 

IFileDialog 548 
IFontDialog 610 
presSpace 

IDMTargetEvent 502 
previous 

IContainerControl:: ColumnCursor 220 
IContainerControl: :ObjectCursor 232 
IContainerControl: :TextCursor 237 
INotebook:: Cursor 1100 
previousPage 

INotebook 1078 
previousSelectedPageHandle 
IPageS electE vent 1135 
printDestination 

IDMSourcePrintEvent 477 
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profile 

IMMAudioCD 838 
proportionalOnly 
IFontDialog 614 
proportionalTicks 
ICircularSlider 46 
pro videEnterS upport 

IDMItemProvider 423 
provideHelpFor 

IDMItemProvider 424 
provideLeaveSupport 

IDMItemProvider 424 
pro videS ourceltems 

IDMItemProvider 424 
IDMItemProviderFor 427 
pro videT argetltemFor 
IDMItemProvider 424 
IDMItemProviderFor 427 
ptr 

IDMImage 394 
pull-down menu 
push button control 

R 

radio button control 
radius 

ICircularSlider 38 
readonly 

IContainerColumn 159 
IContainerControl 215 
readOnlyHeading 

IContainerColumn 160 
readOnlyTitle 

IContainerControl 212 
reallocateString 

ICnrEditHandler 80 
ICnrReallocStringEvent 113 
reallocateText 

ICnrReallocStringEvent 113 
record 

IMMDigital Video 921 
IMMRecordable 1002 
redo 

IMMRecordable 1003 
reference 

IDMItem 419 
reflectHorizontally 
IGBitmap 640 


reflectVertically 
IGBitmap 640 
refresh 

IContainerControl 192, 196, 202 
IContainerObject 248 
IMMDigital V ideo 923 
refreshAllContainers 

IContainerControl 196 
refreshTabs 

INotebook 1086 
IRegionHandle 1136 
regi sterCallbacks 
ICanvas 32 
IContainerControl 207 
IFileDialog 550 
INotebook 1089 
relati ve W indo wRect 
IFlyText 581 
release 

IMMDevice 890 
releasePresSpace 

IDMTargetEvent 502 
removableMedia 
IDMItem 419 
remove 

IPageHandler 1126 
IToolBar 1192 
removeAll 
IGList 665 
remove AllObj ects 

IContainerControl 168 
removeAllPages 
INotebook 1079 
remove All W ithld 
IGList 666 
removeAt 

IGList 666 
removeAtPosition 
IGList 666 
removeColumn 

IContainerControl 180 
removeColumnAt 

IContainerControl 180 
removeCuePoint 

IMMPlayableDevice 973 
removeEntryAt 

IMMAudioCDContents 847 
removeFirst 
IGList 666 
removeFont 
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removeFont (continued) 
IGString 781 
removeFromCell 

IMultiCellCanvas 1054 
removeGraphicBundle 
IGraphic 689 
remo veHelpT ext 

IFlyOverHelpHandler 573 
removeld 

IContainerControl 213 
removelnUse 

IContainerControl 202 
IContainerObject 248 
removeltem 

IDMOperation 441 
removeLast 
IGList 666 
removeLink 

IDDETopicServer 352 
removeObject 

IContainerControl 168 
remo veObj ect At 

IContainerControl 168 
removePage 

INotebook 1079 
removePoint 

IGPolyline 684 
removeRenderer 

IDMHandler 386 
IDMSourceHandler 462 
IDMTargetHandler 506 
removeRMF 

IDMItem 413 
removeSelected 

IContainerControl 203 
removeSelectedObjects 
IContainerControl 168 
removeSourceEmphasis 
ICnrMenuHandler 106 
removeTabSection 
INotebook 1079 
removeType 

IDMItem 410 
renderAtSource 

IDMTargetRenderer 523 
renderComplete 

IDMTargetRenderer 523 
Tenderer 

IDMHandler 386 
IDMItem 414 


Tenderer (continued) 

IDMSourceHandler 462 
IDMTargetHandler 506 
renderingFailed 

IDMTargetEndEvent 494 
renderToName 

IDMTargetRenderer 523 
replaceAt 

IGList 663 
replaceEntryAt 

IMMAudioCDContents 848 
replaceltem 

IDMOperation 442 
replaceRenderer 

IDMHandler 386 
IDMSourceHandler 462 
IDMTargetHandler 506 
requestAck 

IDDERequestDataEvent 335 
requestData 

IDDEClientConversation 304 
IDDETopicServer 355 
requestHotLinkData 

IDDETopicServer 356 
requirements 
requiresFiles 

IMMDevice 876 
requiresPreparation 
IDMItem 406 
resetBackgroundColor 
IGraphicBundle 701 
resetBackgroundMixMode 
IGraphicBundle 699 
resetButton 

IFontDialog 614 
resetClippingRect 
IGString 779 
resetDrawOperation 
IGraphicBundle 703 
resetFillColor 

IGraphicBundle 701 
resetFillPattem 

IGraphicBundle 708 
resetFont 

IGraphicContext 738 
resetLatchedBackgroundColor 
ICustomButton 254 
resetLatchedForegroundColor 
ICustomButton 255 
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resetMajorTabBackgroundColor 
INotebook 1070 
resetMajorTabForegroundColor 
INotebook 1070 
resetMinorTabBackgroundColor 
INotebook 1070 
resetMinorTabForegroundColor 
INotebook 1070 
resetMixMode 

IGraphicBundle 705 
resetPageBackgroundColor 
INotebook 1070 
resetPattemOrigin 

IGraphicBundle 706 
resetPenColor 

IGraphicBundle 701 
resetPenEndingStyle 
IGraphicBundle 711 
resetPen J oiningS ty le 
IGraphicBundle 713 
resetPenPattem 

IGraphicBundle 708 
resetPenType 

IGraphicBundle 710 
resetPenWidth 

IGraphicBundle 710 
resetSplitB arEdgeColor 
ISplitCanvas 1160 
resetSplitB arMiddleColor 
ISplitCanvas 1160 
resetTransformMatrix 
IGraphic 692 
resetTransparentColor 
IGBitmap 637 
IToolBarButton 1213 
resize 

IPageHandler 1126 
resourceLibrary 

IFlyOverHelpHandler 575 
IlnfoArea 796 
resourceLibraryld 
IlnfoArea 801 
resources 
resume 

IMMAudioCD 836 
IMMPlayableDevice 975 
return Value 

IFileDialog 548 
IFontDialog 610 
reversePoints 


reversePoints (continued) 
IGPolyline 684 
rewind 

IMMPlayerPanelHandler 993 
rewindButton 

IMMPlayerPanel 985 
rfAny 

IDM 360 
rfForThisProcess 
IDMItem 412 
rfFrom 

IDMItem 412 
rfObject 

IDM 360 
rfProcess 
IDM 360 
rfSharedMem 
IDM 361 
rfText 

IDM 361 
rfUnknown 
IDM 361 
rightAlign 

ISetCanvas 1150 
rmAny 

IDM 361 
rmDiscard 
IDM 361 
rmfFrom 

IDMItem 412 
rmFile 

IDM 361 
rmFrom 

IDMItem 412 
rmfs 

IDMItem 414 
rmfsFrom 

IDMItem 413 
rmLibrary 
IDM 361 
rmObject 
IDM 361 
rmPrint 

IDM 362 
rotateBy 

IGraphic 692 
ITransformMatrix 1237 
rotateBy 180 

IGBitmap 641 
rotateBy 270 
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rotateBy270 (continued) 
IGBitmap 641 
rotateBy90 

IGBitmap 641 
rotationlncrement 
ICircularSlider 39 
roundedTabs 

INotebook 1094 
rounding 

IGRectangle 757 
rowHeight 

IMultiCellCanvas 1059 

S 

sample 

sample directory location x: 
samplesPerSecond 

IMMAudioBuffer 822 
IMMConfigurableAudio 
save 

IMMRecordable 1003 
saveAs 

IMMRecordable 1004 
saveAsEAType 
IFileDialog 547 
saveHeadphonesSetting 
IMMMasterAudio 954 
saveSpeakersSetting 

IMMMasterAudio 955 
save Volume 

IMMMasterAudio 955 
scaleBy 

IGraphic 693 
ITransformMatrix 1237 
scroll 

IContainerControl 199 
scrollDetailsHorizontally 
IContainerControl 199 
scrollHorizontally 

IContainerControl 199 
scrollToObject 

IContainerControl 200 
scrollVertically 

IContainerControl 200 
scrollViewHorizontallyTo 
IViewPort 1243 
scroll Vie wV erticallyT o 
IViewPort 1244 


seconds 

IMMHourMinSecFrameTime 945 
IMMHourMinSecTime 949 
IMMMinSecFrameTime 961 
IMMTime 1027 

IMMTrackMinSecFrameTime 1035 
seek 

IMMPlayableDevice 978 
seekToEnd 

IMMPlayableDevice 978 
seekToStart 

IMMPlayableDevice 978 
select 

ICollectionViewComboBox 124 
ICollectionViewListBox 139 
IPageHandler 1126 

iii selectableListbox 

IFileDialog 553 
selectedChanged 

862 ICnrHandler 98 

selectedCollectionPosition 

ICollectionViewComboBox 125 
ICollectionViewListBox 139 
selectedElement 

ICollectionViewComboBox 125 
ICollectionViewListBox 139 
selectedElements 

ICollectionViewListBox 140 
selectedFileCount 
IFileDialog 548 
selectedFormat 

IDMSourceRenderEvent 486 
selectedMechanism 

IDMSourceRenderEvent 486 
selectedRMF 
IDMItem 415 
selectld 

IContainerControl 213 
sendCommand 

IMMDevice 894 
sendEvent 

IContainerControl 193 
sequencer 

IMMDevice 899 
serialNumber 

IMMAudioCDContents 849 
serverHandle 

IDDETopicServer 350 
set canvas 
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setAlignment 

ISetCanvas 1143 
setAllEmphasis 
IFont 595 

set Alternate W indo wHandle 

IDMSourcePrepareEvent 473 
setAnimationRate 

IAnimatedButton 10 
setApplicationBusy 

IDDESetAcknowledgelnfoEvent 

setApplicationSpecificData 

IDDESetAcknowledgelnfoEvent 

setArmRange 

ICircularSlider 39 
setAttributes 

IContainerControl 209 
IContainerObject 251 
setB ackgroundColor 

IContainerControl 193 
IGraphicBundle 701 
IGraphicContext 734 
INotebook 1071 
setB ackgroundMixMode 
IGraphicBundle 699 
IGraphicContext 735 
setBalance 

IMM AmpMixer 815 
setBase 

IContainerObject 251 
setB ass 

IMM AmpMixer 815 
setBinding 

INotebook 1068 
setBitmap 

IBitmapControl 19 
IDMImage 391 
IToolBarButton 1207 
setBitmaps 

IAnimatedButton 11 
setB itsPerS ample 

IMMAudioBuffer 822 
IMMConfigurableAudio 863 
setB lockAlignment 

IMMAudioBuffer 823 
IMMConfigurableAudio 863 
setB old 

IFont 595 
setBuffer 

IDDEEvent 327 
setB utton View 
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setButtonView (continued) 
IToolBar 1190 
setBytesPerSecond 

IMMAudioBuffer 823 
IMMConfigurableAudio 864 
ISetCanvas 1138 
ISetCanvas:: Style 1155 
setCaseSensitive 

IDDEBeginEvent 291 
344 setChannels 

IMMAudioBuffer 823 

344 IMMConfigurableAudio 864 

setCharHeight 
IFont 596 
setCharSize 
IFont 596 
setCharWidth 
IFont 596 
setClippingRect 
IGString 779 
setClipRegion 

IGraphicContext 741 
setClosed 

IContainerObject 248 
setCloseOnDestroy 
IMMDevice 888 
setColor 

color support 1272 
setColumnlnfo 

IContainerColumn 157 
setColumnW idth 

IMultiCellCanvas 1059 
setCompletion 

IDMSourceRenderEvent 486 
setContainer 

IContainerColumn 157 
IDMItem 406 
setContainerAttributes 
IContainerControl 209 
setContainerN ame 
IDMItem 407 
setContainerObj ect 
IDMOperation 440 
setContainerRefreshOff 
IDMOperation 440 
setContainerRefreshOn 
IDMOperation 441 
setContents 

IDMItem 409 
setContentType 
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setContentType (continued) 
IMMAudioBuffer 825 
setCurrent 

IContainerControl: :ColumnCursor 220 
IContainerControl: :ObjectCursor 232 
IContainerControl: :TextCursor 237 
INotebook:: Cursor 1100 
setCurrentB itmaplndex 
IAnimatedButton 11 
setCurrentDrawingPosition 
IGraphicContext 724 
setCursor 

IContainerControl 203 
setData 

IDDERequestDataEvent 335 
IMMAudioBuffer 824 
setDataAttributes 

IContainerColumn 157 
setDataOffset 

IContainerColumn 154 
setDeckCount 

ISetCanvas 1141 
setDeckOrientation 
ISetCanvas 1141 
setDecrementBitmaps 
ICircularSlider 39 
setDefaultAttribute 

IContainerControl 174 
setDefaultB ackgroundColor 
IGraphicContext 726 
setDefaultB ackgroundMixMode 
IGraphicContext 726 
setDefaultCell 

IMultiCellCanvas 1060 
setDefaultDataStyle 

IContainerColumn 149 
setDefaultDrawOperation 
IGraphicContext 726 
setDefaultFillColor 

IGraphicContext 727 
setDefaultFillPattern 
IGraphicContext 727 
setDefaultGroupPad 
IToolBar 1193 
setDefaultHeadingStyle 
IContainerColumn 149 
setDefaultMargin 
IToolBar 1193 
setDefaultMisfitWidth 
IToolBar 1194 


setDefaultMixMode 

IGraphicContext 727 
setDefaultOperation 

IDMTargetEnterEvent 499 
setDefaultPad 

IToolBar 1194 
setDefaultPatternOrigin 
IGraphicContext 727 
setDefaultPenColor 

IGraphicContext 727 
setDefaultPenEndingStyle 
IGraphicContext 727 
setDefaultPenJoiningStyle 
IGraphicContext 727 
setDefaultPenPattern 
IGraphicContext 728 
setDefaultPenType 

IGraphicContext 728 
setDefaultPenWidth 

IGraphicContext 728 
setDefaultSourceHandler 
IDMHandler 380 
setDefaultSourceRenderer 
IDMRenderer 450 
setDefaultStyle 

IAnimatedButton 13 
IBitmapControl 21 
ICanvas 31 
ICircularSlider 43 
IContainerControl 205 
ICustomButton 258 
IDMImage 393 
IDrawingCanvas 538 
IFileDialog 549 
IFontDialog 610 
IGraphicPushButton 750 
IlconControl 788 
IMultiCellCanvas 1061 
INotebook 1085 
ISetCanvas 1144 
ISplitCanvas 1164 
IToolBar 1189 
IToolBarButton 1212 
IToolBarContainer 1223 
I ViewPort 1243 
setDefaultTargetHandler 
IDMHandler 380 
setDefaultTargetRenderer 
IDMRenderer 450 
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setDefaultText 

IFlyOverHelpHandler 576 
setDefaultTransparentColor 
IToolBarButton 1213 
setDelayTime 

IFlyOverHelpHandler 578 
setDeleteColumnsOnClose 
IContainerControl 174 
setDeleteObjectsOnClose 
IContainerControl 175 
setDestination 

IMMDigital Video 924 
setDetailsViewSplit 

IContainerControl 180 
setDialogTemplate 

IFileDialog::Settings 557 
IFontDialog:: Settings 617 
setDirection 
IFont 594 
IGArc 631 
setDisabledText 
IlnfoArea 797 
setDiscTitle 

IMMAudioCD 831 
setDisplayPS 

IFontDialog:: Settings 618 
setDisplayWidth 

IContainerColumn 154 
setDraglnfo 

IDMOperation 446 
setDragResult 

IDMOperation 446 
setDrawingArea 

ICustomButtonDrawEvent 266 
setDrawOperation 

IGraphicBundle 704 
IGraphicContext 735 
setDropIndicator 

IDMTargetEnterEvent 499 
setDropOffset 

IDMT argetOperation 516 
setDropPosition 

IDMT argetDropEvent 491 
setDropStatus 
IDMItem 404 
setEditColumn 

IContainerControl 184 
setEditMLE 

IContainerControl 184 
setEditObject 


setEditObject (continued) 
IContainerControl 184 
setElementl 1 

ITransformMatrix 1236 
setElementl 2 

ITransformMatrix 1236 
setElement21 

ITransformMatrix 1236 
setElement22 

ITransformMatrix 1236 
setElement31 

ITransformMatrix 1237 
setElement32 

ITransformMatrix 1237 
setEmphasis 

IContainerControl 209 
IContainerObject 251 
setEnclosingRect 
IGArc 632 
IGEllipse 656 
IGPie 675 
IGRectangle 758 
setEndingPoint 

IG3PointArc 627 
IGLine 659 
setExtendedSelection 

IContainerControl 171 
setFamily 

IFontDialog: Settings 618 
setFileName 

IFileDialog:: Settings 559 
setFillColor 

IGraphicBundle 701 
IGraphicContext 735 
setFillMode 

IGPolygon 680 
setFillPattern 

IGraphicBundle 708 
IGraphicContext 735 
setFloatingPosition 
IToolBar 1188 
setFloatingTitle 
IToolBar 1189 
setFlyT extControl 

IFlyOverHelpHandler 574 
setFlyT extStringT ableOffset 
IFlyOverHelpHandler 577 
setFont 

IFontDialog: Settings 618 
IGraphicContext 738 
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setFont (continued) 

IGString 781 
setFontAngle 
IFont 596 
setFontShear 
IFont 597 
setForegroundColor 
INotebook 1071 
setFormat 

IMMAudioBuffer 825 
IMMConfigurableAudio 865 
setGain 

IMMAmpMixer 815 
setGraphic 

IGraphicPushButton 748 
setGraphicBundle 
IGraphic 689 
IGraphicContext 735 
setGraphicContext 

IDrawingCanvas 537 
setGraphicList 

IDrawingCanvas 538 
setGroup 

IDMItem 407 
setGroupPad 

ISetCanvas 1143 
setHeadinglcon 

IContainerColumn 155 
setHeadingText 

IContainerColumn 155 
setHelpId 

IContainerColumn 155 
setHelpText 

IFlyOverHelpHandler 573 
setHitApertureSize 

IGraphicContext 739 
setHitPoint 

IGraphicContext 739 
setHitSelectable 
IGraphic 690 
setHitSelected 
IGraphic 690 
setlcon 

IContainerObject 248 
IlconControl 787 
setlconSize 

IContainerControl 172 
setlconText 

IContainerObject 249 


setld 

IGraphic 691 
setlmage 

IDMItem 403 
setlmageStyle 

IDMSourceOperation 468 
setlnactiveText 
IlnfoArea 797 
setlncrementB itmaps 
ICircularSlider 39 
setlnitialDelayTime 

IFlyOverHelpHandler 578 
setlnitialDrive 

IFileDialog::Settings 559 
setlnitialFileType 

IFileDialog::Settings 559 
setlntermediatePoint 
IG3 Point Arc 627 
setlnUse 

IContainerControl 203 
IContainerObject 249 
setltalic 

IFont 595 
setltemProvider 

IDMHandler 384 
setltems 

ICollection V iewComboB ox 120 
ICollectionViewListBox 134 
setLastError 

IMMDevice 893 
setLatchedB ackgroundColor 
ICustomButton 255 
setLatchedB itmap 

IToolB arB utton 1207 
setLatchedForegroundColor 
ICustomButton 255 
setLay outDi storted 
ICanvas 30 
IMultiCellCanvas 1057 
ISetCanvas 1142 
ISplitCanvas 1162 
IToolB ar 1185 
IToolB arB utton 1208 
IToolB arContainer 1221 
I ViewPort 1242 
setLay outSize 
ICanvas 34 
setLineCount 

IlnfoArea 795 
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setLineSpacing 

IContainerControl 172 
setLocation 

IToolBar 1194 
IToolB arContainer 1222 
setLongStringTableOffset 
IFlyOverHelpHandler 577 
setLongT extControl 

IFlyOverHelpHandler 575 
setMaj orT abB ackgroundColor 
INotebook 1071 
setMaj orTabForegroundColor 
INotebook 1071 
setMajorTabSize 
INotebook 1086 
setMappingMode 

IGraphicContext 740 
setMargin 

ISetCanvas 1143 
setMarginSize 

IGraphicPushButton 749 
setMediaType 

IMMAudioBuffer 826 
setMessageNotUnderstood 

IDDESetAcknowledgelnfoEvent 
setMinorTabB ackgroundColor 
INotebook 1071 
setMinorT abForegroundColor 
INotebook 1071 
setMinorT abS ize 
INotebook 1086 
setMissingText 
IlnfoArea 797 
setMixedT argetEmphasis 
IContainerControl 172 
setMixMode 

IGraphicBundle 705 
IGraphicContext 736 
setMLEHandler 

ICnrEditHandler 81 
setMMTime 

IMMTime 1032 
setMonitorWindow 

IMMDigital V ideo 922 
setMultipleSelection 

IContainerControl 172 
setName 

IFont 595 
setNativeRMF 
IDMItem 414 
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setN ormalT argetEmphasis 
IContainerControl 172 
setNoSourceRendering 

IDMSourcePrepareEvent 474 
setNumberOfPoints 
IDMImage 391 
setObject 

IDMItem 409 
setOKB uttonT ext 

IFileDialog:: Settings 557 
setOnRemovableMedia 
IDMItem 407 
setOpen 

IContainerObject 249 
IDMItem 407 
setOpenDialog 

IFileDialog:: Settings 559 
setOpenStatus 

IMMDevice 897 
setOperation 

IDMOperation 442 
setOrderedT argetEmphasi s 
IContainerControl 172 
setOrientation 

344 INotebook 1074 

ISplitCanvas 1163 
setOutline 
IFont 595 
setPackType 

ISetCanvas 1143 
setPad 

ISetCanvas 1143 
setPageB ackgroundColor 
INotebook 1072 
setPageB uttonS ize 
INotebook 1077 
setPageSize 

IGraphicContext 729 
setPassDeviceRequested 
IMMDevice 895 
setPattemOrigin 

IGraphicBundle 706 
IGraphicContext 736 
setPenColor 

IGraphicBundle 701 
IGraphicContext 736 
setPenEndingStyle 

IGraphicBundle 712 
IGraphicContext 736 
setPenJoiningStyle 
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setPenJoiningStyle (continued) 
IGraphicBundle 713 
IGraphicContext 737 
setPenPattem 

IGraphicBundle 708 
IGraphicContext 737 
setPenType 

IGraphicBundle 710 
IGraphicContext 737 
setPen Width 

IGraphicBundle 710 
IGraphicContext 737 
setPitch 

IMMAmpMixer 816 
setPlayableDevice 

IMMPlayerPanel 987 
setPoint 

IGPolyline 684 
setPointArray 

IDMImage 391 
setPointer 

IDMImage 392 
setPointerOffset 
IDMImage 392 
IDMSourceOperation 470 
setPoints 

IGPolyline 685 
setPointSize 
IFont 596 

IFontDialog:: Settings 618 
setPosition 

IDMOperation 443 
IFileDialog:: Settings 557 
IFontDialog:: Settings 617 
setPreviewText 

IFontDialog:: Settings 617 
setPrinterPS 

IFontDialog:: Settings 619 
setProfile 

IMMAudioCD 839 
setProgram 

IMMAudioCD 839 
setReadOnlyFlag 

IMMFileMedia 942 
setReference 

IDMItem 407 
setRefreshOff 

IContainerControl 197 
IContainerObject 249 


setRefreshOn 

IContainerControl 197 
IContainerObject 249 
setRelativeWindowRect 
IFlyText 582 
setRenderer 

IDMHandler 386 
IDMItem 415 
IDMSourceHandler 462 
IDMTargetHandler 506 
setRequiresPreparation 
IDMItem 407 
setResourceLibrary 

IFlyOverHelpHandler 575 
IlnfoArea 796 
setRetry 

IDMSourceRenderEvent 486 
setRMFs 

IDMItem 414 
setRotationlncrement 
ICircularSlider 40 
setRounding 

IGRectangle 757 
setRowHeight 

IMultiCellCanvas 1060 
setSamplesPerSecond 

IMMAudioBuffer 823 
IMMConfigurableAudio 865 
setSaveAsDialog 

IFileDialog: Settings 560 
setSelected 

IContainerControl 203 
setSelectedRMF 
IDMItem 415 
setSingleSelection 

IContainerControl 173 
setSizeList 

IFontDialog: Settings 618 
setSource 

IDMOperation 442 
setSourceName 
IDMItem 408 
setSourceOperation 

IDMSourceDiscardEvent 456 
IDMSourcePrintEvent 477 
setSourceWindowHandle 
IDMItem 408 
IDMOperation 443 
setSpeedFormat 

IMMDevice 890 
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setSplitBarEdgeColor 
ISplitCanvas 1160 
setSplitBarMiddleColor 
ISplitCanvas 1161 
setSplitBarThickness 
ISplitCanvas 1163 
setSplitWindowPercentage 
ISplitCanvas 1159 
setStackingPercentage 

IDMSourceOperation 468 
setStandardBitmapSize 
IToolBarButton 1210 
setStandardTextLines 
IToolBarButton 1211 
setStandardTextWidth 
IToolBarButton 1211 
setStartAngle 
IGArc 632 
IGPie 676 
setStartingPoint 

IG3PointArc 627 
IGLine 659 
setStatus 

IDDEEvent 327 
setStatusText 

INotebook 1083 
INotebook::PageSettings 1105 
setStatusTextAlignment 
INotebook 1084 
setStretchSize 

IDMImage 392 
setStrikeout 
IFont 595 
setStringGenerator 

ICollectionViewComboBox 125 
ICollectionViewListBox 140 
setStringTableOffset 
IlnfoArea 798 
setStyle 

IDMImage 392 
IDMTargetOperation 516 
setSupportedRMFs 
IDMRenderer 450 
setSupportedTypes 
IDMRenderer 450 
setSweepAngle 
IGArc 632 
IGPie 676 
setTabBitmap 

INotebook 1086 


setTabBitmap (continued) 

INotebook: :PageSettings 1106 
setTabShape 

INotebook 1087 
setTabText 

INotebook 1087 
INotebook: :PageSettings 1106 
setTabTextAlignment 
INotebook 1088 
setTargetCanRetry 

IDMSourcePrepareEvent 474 
setTargetlnfo 

IDMSourceRenderEvent 487 
IDMTargetDropEvent 491 
setTargetName 
IDMItem 408 
setT argetOperation 

IDMTargetOperation 517 
setTargetWindowHandle 
IDMOperation 443 
setText 

IFlyText 581 
IGString 782 
ISetCanvas 1144 
setTickSpacing 

ICircularSlider 40 
setTimeFormat 

IMMDevice 891 
setTimeToOrdinal 

IMMHourMinSecFrameTime 947 
IMMHourMinSecTime 951 
IMMTime 1031 
Setting classes 
settings 

IFileDialog:: Settings 556 
IFontDialog::Settings 617 
settings class 
setTitle 

IContainerControl 173 
IFileDialog: Settings 557 
IFontDialog: Settings 617 
setTitleAlignment 

IContainerControl 173 
setTitleAttributes 

IContainerColumn 158 
setTitleText 

IToolBarFrameWindow 1229 
setToFirst 

IContainerC ontrol:: ColumnCursor 221 
IContainerControl::ObjectCursor 230 
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setToFirst (continued) 

IContainerControl: :TextCursor 235 
IFont::FaceNameCursor 600 
IFont::PointSizeCursor 603 
IGList: iCursor 671 
IMMAudioCDContents:: Cursor 853 
INotebook:: Cursor 1099 
IToolBar::FrameCursor 1202 
IToolBar::WindowCursor 1205 
setToIdentity 

ITransformMatrix 1237 
setToIndex 

IMMAudioCDContents:: Cursor 853 
setToLast 

IContainerControl:: ColumnCursor 221 
IContainerControl: :ObjectCursor 230 
IContainerControl: :TextCursor 235 
IFont::FaceNameCursor 600 
IFont::PointSizeCursor 603 
IGList: iCursor 671 
IMMAudioCDContents:: Cursor 853 
INotebook:: Cursor 1099 
setToNext 

IContainerControl:: ColumnCursor 221 
IContainerControl: :ObjectCursor 230 
IContainerControl:: T extCursor 23 5 
IFont::FaceNameCursor 600 
IFont::PointSizeCursor 603 
IGList: :Cursor 671 
IMMAudioCDContents:: Cursor 853 
INotebook:: Cursor 1099 
IToolBar::FrameCursor 1202 
IToolBar::WindowCursor 1205 
setT opLeft V ie wPoint 
I ViewPort 1246 
setToPrevious 

IContainerControl:: ColumnCursor 221 
IContainerControl: :ObjectCursor 231 
IContainerControl: :TextCursor 236 
IFont::FaceNameCursor 600 
IFont::PointSizeCursor 603 
IGList: :Cursor 671 
IMMAudioCDContents:: Cursor 853 
INotebook:: Cursor 1099 
setTrackTitle 

IMMAudioCD 832 
setTransformMatrix 
IGraphic 693 
setTransformMethod 
IGraphic 693 


setTransparentColor 
IGBitmap 637 
IToolBarButton 1214 
setTreble 

IMM AmpMixer 816 
setTreeExpandlconSize 
IContainerControl 205 
setTreeltemlcons 

IContainerControl 205 
setTree V iewlndent 

IContainerControl 206 
setTrueType 

IDMItem 410 
setTypes 

IDMItem 410 
setUnderscore 
IFont 595 
setupScrollBars 
I ViewPort 1247 
setUserData 

ICustomButton 258 
INotebook 1068 
INotebook: :PageSettings 1103 
setU serParameter 
IMMDevice 895 
setValid 

IMMTime 1032 
setValue 

ICircularSlider 40 
set View 

IToolBarButton 1214 
setViewOption 
IGBitmap 642 
set V ie wPortRect 

IGraphicContext 729 
setViewWindowSize 
I ViewPort 1244 
setVolume 

IMMDevice 875 
IMMMaster Audio 955 
setWhoDiscards 

IDMSourceDiscardEvent 456 
setWhoPrints 

IDMSourcePrintEvent 477 
setWindow 

IMMDigital Video 924 
INotebook 1082 
setWindowFont 
IFont 597 
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setWorldTransformMatrix 
IGraphicContext 742 
show 

IContainerColumn 155 
IContainerObject 249 
showDetails V iew 

IContainerControl 176 
showDetailsViewTitles 
IContainerControl 173 
sho wFlo wedN ameV iew 
IContainerControl 176 
showFlowedTextView 
IContainerControl 176 
sho wlcon View 

IContainerControl 176 
showMinilcons 

IContainerControl 176 
sho wN ame V iew 

IContainerControl 177 
showObject 

IContainerControl 203 
showSeparators 

IContainerColumn 156 
showSourceEmphasis 

IContainerControl 203 
showSplitBar 

IContainerControl 180 
sho wText View 

IContainerControl 177 
showTitle 

IContainerControl 173 
showTitleSeparator 

IContainerControl 173 
showTreelconView 

IContainerControl 177 
showTreeLine 

IContainerControl 206 
showTreeN ame V iew 

IContainerControl 177 
showTreeTextView 

IContainerControl 177 
singleSelection 

IContainerControl 215 
size 

IGBitmap 636 
ISetCanvas 1145 
sizeTo 

IGBitmap 636 
sizeToBitmap 

IBitmapControl 24 


sizeToGraphic 

IGraphicPushButton 752 
sizeToIcon 

IlconControl 790 
slider control 
slope 

IGLine 659 
slowSpeed 

IMMDigital Video 919 
solidBinding 

INotebook 1094 

sort 

IContainerControl 204 
IGList 666 
sortBylconText 

IContainerControl 204 
source 

IDMOperation 443 
IDMSourceBeginEvent 453 
source And 

IGBitmap 646 
sourceBegin 

IDMSourceHandler 463 
sourceContainer 

IDMCnrltem 369 
sourceDiscard 
IDMItem 416 
IDMSourceHandler 464 
IDMSourceRenderer 481 
IDMTBarButtonltem 527 
sourceEnd 

IDMItem 416 
IDMMenuItem 430 
IDMSourceHandler 464 
IDMSourceRenderer 481 
sourceErase 

IGBitmap 647 
sourcelnvert 

IGBitmap 647 
sourceltemFor 
IDMItem 411 
sourceName 

IDMItem 408 
sourceOfEnd 

IDDEEndEvent 323 
sourceOperation 
IDMItem 404 

IDMSourceDiscardEvent 456 
IDMSourcePrintEvent 477 
sourcePaint 
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sourcePaint (continued) 
IGBitmap 647 
sourcePrepare 
IDMItem 416 
IDMSourceHandler 464 
IDMSourceRenderer 481 
sourcePrint 

IDMItem 417 
IDMSourceHandler 464 
IDMSourceRenderer 481 
sourceRectangle 

IMMDigital V ideo 925 
sourceRender 
IDMItem 417 
IDMSourceHandler 464 
IDMSourceRenderer 481 
sourceToolBar 

IDMTBarButtonltem 527 
sourceT oolB arB utton 

IDMTBarButtonltem 527 
source Window 
IDMItem 408 
IDMOperation 443 
sourceWindowHandle 
IDMItem 408 
IDMOperation 444 
speaker 

IMMDevice 899 
speed 

IMMDigital V ideo 920 
IMMSpeed 1025 
speedFormat 

IMMDevice 891 
spin button control 
spiralBinding 

INotebook 1094 
split canvas 
splitB arEdgeColor 
ISplitCanvas 1161 
splitB arMiddleColor 
ISplitCanvas 1161 
splitB arOff set 

IContainerControl 180 
splitBarThickness 

ISplitCanvas 1164 
ISplitCanvas 1157 
ISplitCanvas: :Style 1169 
splitWindowPercentage 
ISplitCanvas 1160 


squareTabs 

INotebook 1094 
stackingPercentage 

IDMSourceOperation 468 
standardB itmapS ize 


IToolB arB utton 

1211 

standardFormat 


IToolB arB utton 

1217 

standardTextLines 


IToolB arB utton 

1211 

standardTextWidth 


IToolB arB utton 

1211 

startAngle 


IGArc 632 


IGPie 676 


startAnimation 


I AnimatedB utton 

10 


startBoundary Accumulation 
IGraphicContext 721 
startHitTesting 

IGraphicContext 739 
startingPoint 

IG3PointArc 627 
IGLine 659 
startOfTrack 

IMMAudioCDContents 849 
startPositionTracking 

IMMPlayableDevice 974 
startScanningBackward 
IMMAudioCD 836 
startScanningForward 
IMMAudioCD 837 
static text control 
status 

IDDEEvent 327 
status area 
status line 
statusText 

INotebook: :PageSettings 1106 
statusTextAlignment 


INotebook 

1084 

statusTextCenter 

INotebook 

1094 

statusTextLeft 


INotebook 

1094 

statusTextOn 


INotebook: :PageSettings 

statusTextRight 


INotebook 

1094 
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stepBackward 

IMMPlayerPanelHandler 993 
stepB ackwardB utton 

IMMPlayerPanel 985 
stepForward 

IMMPlayerPanelHandler 993 
stepForwardB utton 

IMMPlayerPanel 985 
stepFrame 

IMMPlayableDevice 979 
stop 

IMMAudioCD 837 
IMMPlayableDevice 977 
IMMPlayerPanelHandler 993 
stopAnimation 

IAnimatedButton 10 
stopBoundary Accumulation 
IGraphicContext 722 
stopB utton 

IMMPlayerPanel 985 
stopHandlingEventsFor 
ICnrDrawHandler 65 
ICnrEditHandler 80 
ICnrHandler 97 
ICnrMenuHandler 104 
IFileDialogHandler 566 
IFlyOverHelpHandler 574 
IlnfoArea 795 
IMMDeviceHandler 909 
stopHitTesting 

IGraphicContext 740 
stopPositionTracking 

IMMPlayableDevice 975 
strContents 

IDMItem 420 
stretch 

IDMImage 394 
stretchSize 

IDMImage 392 
string 

IContainerColumn 161 
stringFor 

IStringGenerator 1173 
IStringGeneratorFn 1176 
IStringGeneratorMemberFn 1179 
IStringGeneratorRefMemberFn 1183 
stringGenerator 1171 

ICollectionViewComboBox 126 
ICollectionViewListBox 141 
IStringGeneratorFn 1175 


IStringGeneratorMemberFn 1178 
IStringGeneratorRefMemberFn 1181 
stringT ableOffset 
IlnfoArea 798 
style 

IDMImage 392 
IDMT argetOperation 516 
style classes 
styles 

extended styles 1280 
subscriptOffset 
IFont 592 
subscriptSize 
IFont 592 
successCode 

IMMNotifyEvent 967 
superscriptOffset 
IFont 592 
superscripts ize 
IFont 592 
support classes 
supportedOperations 
IDMItem 408 
supportedOperationsFor 
IDMItem 403 
IDMMenuItem 430 
IDMTBarButtonltem 528 
supportedRMFs 

IDMRenderer 450 
supportedT opics 

IDDEClientConversation 298 
supportedTypes 

IDMRenderer 451 
supportingApplications 

IDDEClientConversation 298 
supportsAudio 

IMMDevice 877 
supportsCommand 
IMMDevice 877 
supportsDigitalTransfer 
IMMDevice 877 
supportsDisableEject 
IMMDevice 878 
supportsEject 

IMMDevice 878 
supportsOperation 

IDMTargetRenderer 521 
supportsOverlayGraphics 
IMMDigital Video 913 
supportsPlay 
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supportsPlay (continued) 
IMMDevice 878 
supportsRecord 

IMMDevice 879 
supportsRecordlnsertion 
IMMDevice 879 
supportsReverse 

IMMDigital Video 913 
supportsRMF 
IDMItem 414 
supportsSave 

IMMDevice 880 
supportsSizing 

IMMDigital Video 913 
supportsStreaming 
IMMDevice 880 
supportsS tretchT oFit 

IMMDigital Video 914 
supports Video 

IMMDevice 880 
supports Volume Adjustment 
IMMDevice 881 
supports W aveFormat 

IMM Wave Audio 1043 
sweepAngle 
IGArc 632 
IGPie 676 
sylkFormat 
IDDE 275 
system menu 

T 

tabBitmap 

INotebook::PageSettings 1107 
IPageRemoveEvent 1132 
tabShape 

INotebook 1088 
tabText 

INotebook: :PageSettings 1107 
tabTextAlignment 
INotebook 1088 
tabTextCenter 

INotebook 1095 
tabTextLeft 

INotebook 1095 
tabTextRight 

INotebook 1095 
targetCanRetry 

IDMSourcePrepareEvent 474 


targetCanRetry (continued) 
IDMTargetEndEvent 495 
targetDrop 

IDMCnrltem 368 
IDMEFItem 373 
IDMItem 417 
IDMMLEItem 435 
IDMTargetHandler 507 
IDMTBarButtonltem 526 
IDMToolBarltem 532 
targetEnd 

IDMItem 417 
IDMTargetHandler 508 
targetEnter 

IDMTargetHandler 508 
targetHelp 

IDMTargetHandler 508 
targetlnfo 

IDMSourceRenderEvent 487 
IDMTargetDropEvent 491 
IDMTargetEndEvent 495 
targetLeave 

IDMTargetHandler 508 
targetName 

IDMItem 409 
IDMSourceRenderEvent 487 
targetOperation 
IDMItem 404 
IDMTargetOperation 517 
targetRender 

IDMTargetRenderer 521 
targetRenderComplete 

IDMTargetRenderer 522 
targetRenderPrepare 

IDMTargetRenderer 522 
targetToolBar 

IDMTBarButtonltem 527 
targetToolBarButton 

IDMTBarButtonltem 528 
targetWindow 

IDMOperation 444 
IDMSourceRenderEvent 487 
targetWindowHandle 
IDMOperation 444 
IDMSourceRenderEvent 487 

text 

IDM 360 
IGString 782 
IMMErrorlnfo 935 
ISetCanvas 1145 
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text string 
TextCursor 

IContainerControl: :TextCursor 234 
textFormat 
IDDE 275 
textld 

ISetCanvas 1147 
textLines 

IFont 592 
textRectangle 

IContainerControl 191 
textRef 

ICnrEditEvent 76 
textSize 

ICnrEditEvent 76 
text View 

IContainerControl 212 
textVisible 

IToolBarButton 1217 
textWidth 
IFont 593 
thousandths 

IMMTime 1027 
threads 

throwMMError 

IMMErrorlnfo 935 
tickSpacing 

ICircularSlider 40 
tiffFormat 
IDDE 275 
time 

IContainerColumn 159 
timeFormat 

IMMDevice 891 

title 

IContainerControl 174 
IFileDialog::Settings 558 
titleAttributes 

IContainerColumn 158 
titleld 

IContainerControl 214 
titleRectangle 

IContainerControl 174 
titleSeparator 

IContainerControl 212 
titleText 

IToolBarFrameWindow 1229 
titleVisibleld 

IContainerControl 214 
tokenForWPSObject 


tokenForWPSObject (continued) 
IDMItem 411 
IToolBar 1184 
IToolBar::FrameCursor 1201 
IToolBar::Style 1203 
IToolBar: :WindowCursor 1204 
toolBarAt 

IToolBar 1186 
toolBarButton 1206 
IDM 360 

IToolBarButton: :Style 1220 
toolBarContainer 1221 
IToolBar 1190 
IToolBarContainer:: Style 1227 
IToolBarFrameWindow 1228 
tools 
topAlign 

ISetCanvas 1150 
topGraphicUnderPoint 
IGList 664 
topHandle 

IContainerControl 207 
ISetCanvas 1141 
topic 

IDDEActiveServer 287 
IDDEBeginEvent 291 
IDDEClientConversation 300 
IDDEClientEndEvent 312 
IDDETopicServer 350 
topLeftV ie wPoint 
IViewPort 1247 
topPage 

INotebook 1078 
totalPages 

INotebook 1082 
track 

IMMAudioCDContents 849 
IMMTrackMinSecFrameTime 1036 
trackBackward 

IMMAudioCD 838 
trackForward 

IMMAudioCD 838 
tracks tartedld 

IMMAudioCD 844 
trackTitle 

IMMAudioCD 832 
transactionType 

IDDEAcknowledgeEvent 278 
transformMatrix 1233 
IGraphic 693 
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transformMethod 
IGraphic 693 
translateAudioFlag 

IMMConfigurableAudio 868 
IMMDigital Video 931 
translateBy 

IGraphic 694 
ITransformMatrix 1238 
transparent 

IDMImage 394 
transparentColor 
IGBitmap 637 
IToolBarButton 1214 
transposeXForY 
IGBitmap 641 
treble 

IMMAmpMixer 816 
treeCollapsed 

ICnrHandler 98 
treeExpanded 

ICnrHandler 98 
tree View 

IContainerControl 212 
trueType 

IDMItem 410 
tryT oLoadB itmap 
IGBitmap 644 
tumToPage 

INotebook 1078 

Two-Dimensional Graphic Classes xx 
overview xx 

type names, conventions xxii 
types 

IDMItem 410 

U 

undo 

IMMRecordable 1004 
uniqueDiscIdentifier 
IMMAudioCD 841 
unknown 
IDM 360 
IDMItem 420 
IDMOperation 447 
unlatch 

ICustomButton 257 
unlockDoor 

IMMRemovableMedia 1011 


unregisterCallbacks 
ICanvas 33 
IContainerControl 208 
IFileDialog 551 
INotebook 1090 
upc 

IMMAudioCD 832 
IMMCDXA 856 
updateForlnsert 

ICnr Allocator 53 
useBitmapOnly 
IFont 589 
useCount 

IContainerObject 251 
u seDefaultMonitorWindo w 
IMMDigital V ideo 922 
useDefaultPaintHandler 
IDrawingCanvas 540 
useDefaultWindow 

IMMDigital Video 926 
useldForB itmap 

IToolBarButton 1218 
useldForText 

IToolBarButton 1218 
useNonPropOnly 
IFont 589 

User Interface Class Library 
description xix 
userData 

ICustomButton 258 
INotebook: :PageSettings 1103 
userParameter 

IMMCuePointEvent 871 
IMMDevice 896 
IMMNotifyEvent 966 
IMMPositionChangeEvent 996 
useVectorOnly 
IFont 589 

V 

validate 

IFileDialogHandler 568 
validateName 

IFileDialogHandler 569 
validObject 

ICnrEnterEvent 90 
value 

ICircularSlider 40 
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valueld 

ICircularSlider 45 
vectorOnly 

IFontDialog 614 
verifyPointers 

IContainerControl 215 
vertical 

IGraphicBundle 716 
ISplitCanvas 1167 
verticalDataAlignment 
IContainerColumn 156 
verticalDecks 

ISetCanvas 1150 
verticalHeadingAlignment 
IContainerColumn 156 
verticalScrollBar 
I ViewPort 1241 
verticalSeparator 

IContainerColumn 159 
videoDisc 

IMMDevice 899 
videoFileHeight 

IMMDigital Video 926 
videoFileName 

IMMDigital Video 926 
videoFileWidth 

IMMDigital V ideo 927 
videoHeight 

IMMDigital V ideo 927 
videoTape 

IMMDevice 899 
video Width 

IMMDigital V ideo 927 
view 

IToolBarButton 1214 
viewOption 

IGBitmap 642 
viewport 1239 
IViewPort:: Style 1251 
vie wPortOn W indo w 

IContainerControl 195 
vie wPortOn W orkspace 
IContainerControl 195 
viewPortRect 

IGraphicContext 729 
viewWindow 

IViewPort 1244 
vie w Windo wDrawRectangle 
IViewPort 1244 
viewWindowSize 


viewWindowSize (continued) 
IViewPort 1245 
viewWindowSizeld 
IViewPort 1248 
visibleRectangle 

IlconControl 784 
ISplitCanvas 1163 
visibleTitle 

IContainerControl 212 
visibleTreeLine 

IContainerControl 212 
Visual Age C++ 
volume 

IMMDevice 876 
IMMMasterAudio 956 

W 

wasDragAfter 

IDMT argetOperation 516 
wasPassDeviceRequested 
IMMDevice 896 
wasTargetSuccessful 

IDMSourceEndEvent 459 
waveAudio 

IMMDevice 900 
white 

IGBitmap 647 
whoDiscards 

IDMSourceDiscardEvent 456 
whoPrints 

IDMSourcePrintEvent 477 
willDeleteColumnsOnClose 
IContainerControl 175 
willDeleteObjectsOnClose 
IContainerControl 175 
window 

INotebook 1083 
window classes 
windowAt 

IToolBar 1186 
Windo wCursor 

IToolBar: :WindowCursor 1204 
windowInCell 

IMultiCellCanvas 1055 
windows 
windowScrolled 
ICnrHandler 98 
worldTransformMatrix 
IGraphicContext 742 
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writeToFile 

IGBitmap 643 


X 

X/Motif messages 
xHeight 

IFontDialog 609 
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If there is something you like—or dislike—about this book, please let us know. You can use one of the 
methods listed below to send your comments to IBM. If you want a reply, include your name, address, 
and telephone number. If you are communicating electronically, include the book title, publication number, 
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